Course contentsShow
← System Design
Lesson 1879 of 1,91945. API Design and VersioningFree lesson

HTTP Status Codes: Choosing the Right Response

Using 2xx, 4xx, 5xx status codes correctly to communicate success, client errors, and server errors.

HTTP Status Codes: Choosing the Right Response

What you'll learn: How to select appropriate HTTP status codes to clearly communicate the outcome of API requests.

Why Status Codes Matter

When you design RESTful APIs, status codes are your universal language for telling clients what happened with their request. Think of them like traffic signals: green (2xx) means go ahead, yellow/red (4xx) means you made a mistake, and flashing red (5xx) means something's broken on our end.

The Three Key Families

2xx: Success

Use these when everything worked as intended:

  • 200 OK – Standard success for GET, PUT, DELETE
  • 201 Created – Resource successfully created (POST, typically)
  • 204 No Content – Success, but no body to return (often DELETE)

4xx: Client Errors

Use these when the client sent a bad request:

  • 400 Bad Request – Malformed JSON, invalid data format
  • 401 Unauthorized – Missing or invalid authentication
  • 403 Forbidden – Authenticated but lacks permission
  • 404 Not Found – Resource doesn't exist
  • 409 Conflict – Request conflicts with current state (duplicate creation)
  • 429 Too Many Requests – Rate limit exceeded

5xx: Server Errors

Use these when your system failed:

  • 500 Internal Server Error – Generic server failure
  • 502 Bad Gateway – Upstream service returned invalid response
  • 503 Service Unavailable – Temporary overload or maintenance
  • 504 Gateway Timeout – Upstream service didn't respond in time

Choosing Correctly

The golden rule: 4xx means the client shouldn't retry without changes; 5xx means retry might work later. If a crawler hits 404, it shouldn't retry. If it hits 503, retrying after a delay makes sense.

Never return 200 with an error message in the body—that breaks HTTP semantics and confuses clients, caching layers, and monitoring systems.

Key Takeaway: Pick status codes that accurately reflect who caused the issue (client vs server) and whether the operation succeeded, guiding clients on next steps.