HTTP Status Codes Reference
HTTP status codes describe the outcome of one request at the protocol boundary. Use the most specific standard code that matches the actual server behavior, then provide a stable machine-readable error body where clients need detail.
Status code classes
| Range | Class | Meaning |
|---|---|---|
| 100–199 | Informational | Interim protocol state before the final response. |
| 200–299 | Successful | The request was received, understood, and handled successfully. |
| 300–399 | Redirection | Another location or cached representation is involved. |
| 400–499 | Client error | The request cannot succeed without a client-side change or authorization decision. |
| 500–599 | Server error | The server failed to fulfill an apparently valid request. |
Common successful responses
| Code | Name | Typical API use |
|---|---|---|
| 200 | OK | A successful read or action with a response representation. |
| 201 | Created | A new resource was created; often paired with a Location header. |
| 202 | Accepted | Work was accepted but has not completed; expose operation status. |
| 204 | No Content | The operation succeeded and no response body is returned. |
| 206 | Partial Content | A byte range was served in response to a valid Range request. |
Do not send a JSON body with 204. Use 202 only when processing is genuinely asynchronous, and give clients a documented way to observe completion or failure.
Redirect and cache responses
301 and 308 describe permanent moves; 308 preserves method and body. 302, 303, and 307 have different method-handling semantics, so APIs should avoid ambiguous redirect chains. 304 Not Modified answers a conditional request and carries no normal representation body. Clients and intermediaries must evaluate the relevant cache validators and headers.
Common client errors
| Code | Use |
|---|---|
| 400 | Malformed request syntax or a general invalid request under the API convention. |
| 401 | Authentication credentials are missing, expired, or invalid. |
| 403 | The authenticated caller is not permitted to perform the action. |
| 404 | No matching route or visible resource was found. |
| 405 | The target does not support the request method; include Allow. |
| 409 | The request conflicts with current resource state. |
| 415 | The request representation uses an unsupported media type. |
| 422 | Well-formed content fails semantic validation under a common API convention. |
| 429 | A request limit was exceeded; Retry-After may guide recovery. |
Common server and gateway errors
500 is an unexpected server failure. 502 means a gateway received a failed or invalid upstream response. 503 signals temporary unavailability such as overload or maintenance. 504 means a gateway deadline expired. Do not expose stack traces or infrastructure secrets. Correlate a safe request ID with internal logs.
Retry rules
Status class alone does not make a request retryable. Respect documented Retry-After values, use bounded exponential backoff with jitter, and stop at the caller deadline. Safe reads are easier to retry. Writes require idempotency keys or another way to discover whether the first attempt changed state. An HTTP timeout or gateway error does not prove that the upstream performed no work.
Frequently Asked Questions
Does 200 always mean business success?
Interpret it with the documented representation and operation contract.
Should every 5xx be retried?
No. Retry only safe operations under a bounded policy.
How do 401 and 403 differ?
401 concerns authentication; 403 concerns permission.