HTTP status codes are 3-digit numbers returned by a web server to indicate the result of a client's request/response.
In API development choosing the right codes enhances clarity, debugging, and align with industry standard.
Why it Important?
- Automated error handling in client applications
- Proper caching behavior by intermediary servers
- Meaningful monitoring and alerting in production systems
- Better developer experience during integration
The Five Categories (1xx–5xx):
- Informational responses (100 – 199)
- Successful responses (200 – 299)
- Redirection messages (300 – 399)
- Client error responses (400 – 499)
- Server error responses (500 – 599)
🟦 1xx – Informational
| Code | Name | Description | Typical Use |
|---|---|---|---|
| 100 | Continue | Server has received the headers; client should continue. | Rarely used directly; used in chunked requests. |
| 101 | Switching Protocols | Server switches protocols as requested by the client. | WebSocket handshake upgrade. |
| 102 | Processing | WebDAV: server is processing but no response yet. | Long-running requests, WebDAV. |
| 103 | Early Hints | Suggests headers (like Link) before final response. | Performance optimizations (preload assets). |
🟩 2xx – Success
| Code | Name | Description | Typical Use |
|---|---|---|---|
| 200 | OK | Request succeeded; response depends on method. | GET returns resource; POST may return created resource. |
| 201 | Created | Resource successfully created. | POST /resources -> response includes Location header. |
| 202 | Accepted | Request accepted for processing, not completed. | Async operations queued. |
| 203 | Non-Authoritative Information | Returned meta-information modified from origin. | Proxy or transformation scenarios. |
| 204 | No Content | Success but no body returned. | Successful DELETE or PUT with no body response. |
| 205 | Reset Content | Client should reset the view. | HTML forms reset after a successful request. |
| 206 | Partial Content | Partial GET due to Range header. | Resuming downloads, media streaming. |
| 207 | Multi-Status | WebDAV; multiple separate responses. | Batch WebDAV operations. |
| 208 | Already Reported | WebDAV: members of a DAV binding already reported. | WebDAV multistatus optimization. |
| 226 | IM Used | Delta encoding; server fulfilled with a delta. | Rare: HTTP Delta encoding (RFC 3229). |
🟨 3xx – Redirection
| Code | Name | Description | Typical Use |
|---|---|---|---|
| 300 | Multiple Choices | Multiple representation options for the resource. | Content negotiation or choices page. |
| 301 | Moved Permanently | Resource moved permanently; update bookmarks. | Permanent redirects (SEO-friendly). |
| 302 | Found (Temporary Redirect) | Temporary redirect; user-agent may change method. | Temporarily redirecting resources. |
| 303 | See Other | Redirect using GET to retrieve result. | After POST, redirect to a GET-able result (PRG pattern). |
| 304 | Not Modified | Resource not modified; use cached copy. | Conditional GET with ETag/If-Modified-Since. |
| 305 | Use Proxy (deprecated) | Must use the proxy given in Location. | Deprecated — avoid using. |
| 307 | Temporary Redirect | Temporary redirect; method and body must not change. | Safer temporary redirect than 302 for non-GET methods. |
| 308 | Permanent Redirect | Permanent redirect; method and body preserved. | Permanent redirect that preserves method (replacement for 301). |
🟥 4xx – Client Errors
| Code | Name | Description | Typical Use |
|---|---|---|---|
| 400 | Bad Request | Malformed syntax or invalid request. | Validation errors, parse failures. |
| 401 | Unauthorized | Authentication required or failed. | Missing/invalid authentication token. |
| 402 | Payment Required | Reserved for future use. | Rarely used (some APIs use it for billing). |
| 403 | Forbidden | Server understood but refuses to authorize. | Valid auth but insufficient permissions. |
| 404 | Not Found | Resource not found. | Wrong URL, missing resource. |
| 405 | Method Not Allowed | Method not allowed for resource. | POST used where only GET allowed. |
| 406 | Not Acceptable | Content negotiation failed. | Requested content type not supported. |
| 407 | Proxy Authentication Required | Client must authenticate with proxy. | Requests through an authenticating proxy. |
| 408 | Request Timeout | Server timed out waiting for the request. | Large uploads interrupted or slow clients. |
| 409 | Conflict | Request could not be completed because of a conflict. | Versioning conflicts, duplicate unique fields. |
| 410 | Gone | Resource permanently removed. | Deleted resources that should not be requested again. |
| 411 | Length Required | Content-Length header required. | Servers requiring known-length requests. |
| 412 | Precondition Failed | One of the preconditions failed (If-Match, etc.). | Optimistic concurrency control (ETag mismatch). |
| 413 | Payload Too Large | Request entity too large. | Large file uploads exceeding limits. |
| 414 | URI Too Long | Request URI too long. | Overlong query strings or improperly built URLs. |
| 415 | Unsupported Media Type | Unsupported payload media type. | Sending XML to an API that accepts JSON only. |
| 416 | Range Not Satisfiable | Invalid Range header value. | Requesting byte ranges outside file length. |
| 417 | Expectation Failed | Server cannot meet Expect header. | Rare; related to Expect: 100-continue. |
| 418 | I'm a teapot | April Fools' joke (RFC 2324). | Easter-egg; not used in real APIs. |
| 421 | Misdirected Request | Server not able to produce response. | Requests routed incorrectly in multi-host setups. |
| 422 | Unprocessable Entity | Semantic errors in the request entity. | Validation errors with well-formed JSON. |
| 423 | Locked | Resource is locked (WebDAV). | Concurrency controls in WebDAV. |
| 424 | Failed Dependency | Operation failed due to earlier failure. | A step in a multi-step request failed. |
| 425 | Too Early | Server reluctant to process early data. | Protect against replay attacks (experimental). |
| 426 | Upgrade Required | Client should switch protocols. | Require TLS or a different protocol. |
| 428 | Precondition Required | Require preconditions (e.g., If-Match). | Prevent lost updates by requiring ETags. |
| 429 | Too Many Requests | Rate limiting; client should slow down. | API throttling; include Retry-After header. |
| 431 | Request Header Fields Too Large | Headers too large to process. | Oversized cookies or headers. |
| 451 | Unavailable For Legal Reasons | Resource unavailable due to legal reasons. | Geo-blocking or court-ordered takedown. |
⛔ 5xx – Server Errors
| Code | Name | Description | Typical Use |
|---|---|---|---|
| 500 | Internal Server Error | Generic server error. | Unhandled exceptions, server crashes. |
| 501 | Not Implemented | Server does not support requested functionality. | Feature not implemented on server. |
| 502 | Bad Gateway | Invalid response from upstream server. | Reverse proxy or gateway error. |
| 503 | Service Unavailable | Server overloaded or down for maintenance. | Temporary downtime; include Retry-After. |
| 504 | Gateway Timeout | Upstream server timed out. | Slow upstream service causing timeout. |
| 505 | HTTP Version Not Supported | HTTP version not supported by server. | Rare in modern APIs. |
| 506 | Variant Also Negotiates | Server configuration error in content negotiation. | Rare; indicates misconfiguration. |
| 507 | Insufficient Storage | WebDAV: insufficient storage. | Servers running out of storage for the request. |
| 508 | Loop Detected | WebDAV: infinite loop detected. | Misconfigured resource references. |
| 509 | Bandwidth Limit Exceeded (non-standard) | Informational; not an official status. | Some servers/providers use this for bandwidth caps. |
| 510 | Not Extended | Further extensions required to fulfill request. | Rare; extension negotiation needed. |
| 511 | Network Authentication Required | Client needs to authenticate to gain network access. | Captive portal or network auth required. |
Conclusion:
HTTP status codes are not just numbers—they are a language between the front-end and back-end. A well-designed API should use them properly to communicate intent, success, or failure. This improves both developer experience and debuggability.
Top comments (0)