Stage 4. Response Status Codes
HTTP status code is the first result signal your server provides. Client SDKs, retry engines, dashboards, and alerts primarily react to that signal. For that reason, status code discipline is part of production reliability, not cosmetic API style.
A practical way to reason about codes is through three groups. 2xx means successful processing. 4xx means request/client/context issue. 5xx means server-side failure. Teams that apply this mapping consistently gain faster incident triage and clearer operational metrics.
In day-to-day API work, a small subset of codes matters most. 200 OK for successful read/update with body, 201 Created for creation, 204 No Content for successful operations without payload. On the failure side, 400, 401, 403, 404, 409, and 422 cover most client-facing problems, while 500 represents unexpected server faults.
The "always return 200" pattern feels convenient early, but it breaks protocol semantics. Clients must parse custom body flags, monitoring loses true error signals, and retries misbehave. Over time this creates brittle client logic and expensive maintenance.
Status and body should reinforce each other. A 409 Conflict should include a conflict-oriented message and machine-readable type, not a generic failure string. Integration teams often automate behavior based on the combination of status and error type.
{
"error": "conflict",
"message": "order already confirmed",
"traceId": "a733ed51"
}
401 vs 403 is another high-value distinction. 401 means authentication is missing or invalid. 403 means authentication is valid but permissions are insufficient. Mixing these codes causes poor UX and incorrect client recovery behavior.
422 Unprocessable Entity is useful when JSON is syntactically valid but violates business constraints. This cleanly separates malformed input (400) from semantically invalid action (422), especially helpful for complex form workflows.
Consistency across endpoints is critical. If identical failure scenarios produce different status codes in different modules, clients become branch-heavy and QA matrices explode. A stable status policy reduces both integration cost and support load.
HTTP Status Reference Table
| Class | Code | Name | Practical meaning |
|---|---|---|---|
| 1xx | 100 | Continue | Request headers were received; client can continue sending the body. |
| 1xx | 101 | Switching Protocols | Server agrees to switch protocol as requested. |
| 1xx | 103 | Early Hints | Preliminary response so the client can preload linked resources. |
| 2xx | 200 | OK | Standard success response. |
| 2xx | 201 | Created | Request succeeded and created a new resource. |
| 2xx | 202 | Accepted | Request accepted for processing, but not finished yet. |
| 2xx | 203 | Non-Authoritative Information | Success, but returned metadata/body may come from a transformed or secondary source. |
| 2xx | 204 | No Content | Success with no response body. |
| 2xx | 205 | Reset Content | Success with no body; client should reset its current view/form state. |
| 2xx | 206 | Partial Content | Server returned only part of the resource (range request). |
| 3xx | 300 | Multiple Choices | Multiple representations/targets are available. |
| 3xx | 301 | Moved Permanently | Resource permanently moved to a new URL. |
| 3xx | 302 | Found | Resource temporarily located at another URL. |
| 3xx | 303 | See Other | Client should retrieve result at another URL (commonly after POST). |
| 3xx | 304 | Not Modified | Cached version is still valid; no new payload needed. |
| 3xx | 307 | Temporary Redirect | Temporary redirect while keeping the original HTTP method. |
| 3xx | 308 | Permanent Redirect | Permanent redirect while keeping the original HTTP method. |
| 4xx | 400 | Bad Request | Server cannot process the request because syntax/shape is invalid. |
| 4xx | 401 | Unauthorized | Authentication is missing, invalid, or failed. |
| 4xx | 402 | Payment Required | Reserved code; generally not used in normal APIs. |
| 4xx | 403 | Forbidden | Authenticated (or understood), but operation is not allowed. |
| 4xx | 404 | Not Found | Requested resource cannot be found. |
| 4xx | 405 | Method Not Allowed | HTTP method is not supported for this resource. |
| 4xx | 406 | Not Acceptable | Server cannot produce a response matching client Accept constraints. |
| 4xx | 407 | Proxy Authentication Required | Client must authenticate with the proxy first. |
| 4xx | 408 | Request Timeout | Server timed out waiting for the request. |
| 4xx | 409 | Conflict | Request conflicts with current resource state. |
| 4xx | 410 | Gone | Resource was removed and is no longer available. |
| 4xx | 411 | Length Required | Content-Length header is required but missing. |
| 4xx | 412 | Precondition Failed | Conditional request precondition evaluated to false. |
| 4xx | 413 | Request Too Large | Request body is larger than server limit. |
| 4xx | 414 | Request-URI Too Long | URI is longer than the server is willing to process. |
| 4xx | 415 | Unsupported Media Type | Payload media type is not supported. |
| 4xx | 416 | Range Not Satisfiable | Requested byte range cannot be served. |
| 4xx | 417 | Expectation Failed | Server cannot satisfy the Expect header requirements. |
| 5xx | 500 | Internal Server Error | Generic unexpected server-side failure. |
| 5xx | 501 | Not Implemented | Server does not support requested method/behavior. |
| 5xx | 502 | Bad Gateway | Upstream service returned an invalid response. |
| 5xx | 503 | Service Unavailable | Server is unavailable (overloaded or down). |
| 5xx | 504 | Gateway Timeout | Upstream service did not respond in time. |
| 5xx | 505 | HTTP Version Not Supported | Server does not support the request's HTTP version. |
| 5xx | 511 | Network Authentication Required | Network access requires authentication first. |
Practical scenario
In a payment API, duplicate-operation conflict returned 409 in one endpoint but 200 with success=false in another. Mobile clients treated one flow as success and suppressed user warnings. After status normalization and unified error schema, client behavior became consistent, support tickets dropped, and monitoring finally reflected real conflict rates.