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, DELETE201 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 format401 Unauthorized– Missing or invalid authentication403 Forbidden– Authenticated but lacks permission404 Not Found– Resource doesn't exist409 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 failure502 Bad Gateway– Upstream service returned invalid response503 Service Unavailable– Temporary overload or maintenance504 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.