This content originally appeared on DEV Community and was authored by Md Asaduzzaman
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.
This content originally appeared on DEV Community and was authored by Md Asaduzzaman