HTTP Status Codes
Every HTTP response status code — what it means, when to use it, and common pitfalls.
How to Use
- Use the search field at the top to filter codes by number, name, or description.
- Codes are grouped by class: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error.
- Each entry shows the code, official name, and a short note about when to use it (or what it really means in practice).
- Use this when designing REST APIs to pick the right code for each response, or when debugging unexpected responses from a third-party service.
- Cross-reference with RFC 9110 (the current authoritative spec) when designing public APIs.
1xx — Informational
| Code | Name | Notes |
|---|---|---|
| 100 | Continue | Client should continue sending request body |
| 101 | Switching Protocols | WebSocket upgrade |
| 102 | Processing | WebDAV — still working |
| 103 | Early Hints | Preload hints before final response |
2xx — Success
| Code | Name | Notes |
|---|---|---|
| 200 | OK | Standard success |
| 201 | Created | Resource created — return Location header |
| 202 | Accepted | Async — work queued |
| 204 | No Content | Success but no body (DELETE, PUT often) |
| 206 | Partial Content | Range request response |
3xx — Redirection
| Code | Name | Notes |
|---|---|---|
| 301 | Moved Permanently | Cached by browsers — use for permanent changes |
| 302 | Found | Temporary redirect (legacy — prefer 307) |
| 303 | See Other | POST → GET redirect (PRG pattern) |
| 304 | Not Modified | Cache validator — no body |
| 307 | Temporary Redirect | Preserves method (unlike 302) |
| 308 | Permanent Redirect | Preserves method (unlike 301) |
4xx — Client Error
| Code | Name | Notes |
|---|---|---|
| 400 | Bad Request | Malformed request |
| 401 | Unauthorized | Needs authentication (WWW-Authenticate header) |
| 402 | Payment Required | Reserved — rare in the wild |
| 403 | Forbidden | Authenticated but not allowed |
| 404 | Not Found | Resource doesn't exist |
| 405 | Method Not Allowed | Return Allow header |
| 406 | Not Acceptable | Content negotiation failed |
| 408 | Request Timeout | Client took too long |
| 409 | Conflict | State conflict — e.g. version mismatch |
| 410 | Gone | Permanently removed (stronger than 404) |
| 413 | Payload Too Large | Body too big |
| 415 | Unsupported Media Type | Bad Content-Type |
| 418 | I'm a teapot | RFC 2324 (April Fools) |
| 422 | Unprocessable Entity | Well-formed but semantically wrong (WebDAV, common in REST) |
| 429 | Too Many Requests | Rate limited — return Retry-After |
5xx — Server Error
| Code | Name | Notes |
|---|---|---|
| 500 | Internal Server Error | Catch-all — server crashed |
| 501 | Not Implemented | Method/feature not supported |
| 502 | Bad Gateway | Proxy got an invalid upstream response |
| 503 | Service Unavailable | Overloaded or maintenance — return Retry-After |
| 504 | Gateway Timeout | Upstream took too long |
| 505 | HTTP Version Not Supported | |
| 507 | Insufficient Storage | WebDAV |
| 508 | Loop Detected | WebDAV — infinite recursion |
Notes
- Idempotency: GET, HEAD, PUT, DELETE are idempotent — safe to retry on timeout. POST is not.
- Redirect loops: browsers follow up to ~20 redirects then fail with a client error.
Frequently Asked Questions
What is HTTP status code 200?
200 OK is the standard success response. It means the request succeeded and the response body contains the requested resource (for GET) or confirmation of the operation (for POST/PUT). For successful operations that return no body, use 204 No Content instead.
When should I use 401 vs 403?
401 Unauthorized means 'you haven't authenticated' — the response should include a WWW-Authenticate header indicating how to authenticate. 403 Forbidden means 'you ARE authenticated but you're not allowed to do this.' If a user types in a password and gets it wrong: 401. If they're logged in as a regular user trying to access an admin page: 403.
What's the difference between 301 and 302?
301 Moved Permanently — browsers cache the redirect aggressively, search engines update their indexes. Use this when content has truly moved and isn't coming back. 302 Found (legacy) and 307 Temporary Redirect — the redirect is temporary, browsers don't cache. Prefer 307 over 302 because 307 explicitly preserves the HTTP method (302 historically allowed clients to silently change POST to GET).
When should I use 422 Unprocessable Entity?
When the request body parsed correctly but contains semantically invalid data — for example, a JSON body with a valid email field whose value isn't a real email address, or a date in the past when a future date was required. 400 Bad Request is for malformed bodies (broken JSON, missing required fields). 422 is widely used in REST APIs but is technically a WebDAV extension; 400 is the more conservative alternative.
What does 429 Too Many Requests mean?
Rate limited. The client should slow down or wait. The response should include a Retry-After header indicating either a date or a number of seconds before the next request. Most modern APIs use 429 for rate limiting; some older systems use 503 Service Unavailable for the same purpose.
Why is 418 a teapot?
An IETF April Fool's joke. RFC 2324 (1998) and RFC 7168 (2014) define the Hyper Text Coffee Pot Control Protocol, where 418 indicates the server is a teapot and cannot brew coffee. It has no production use but persists as Easter eggs in many web frameworks (Node.js, Django, ASP.NET) and shows up in real APIs occasionally as a deliberate joke or sentinel.
Common Use Cases
Designing REST API responses
Pick the right status code for each endpoint — POST creates return 201 with Location, deletes return 204, conditional updates return 412 on mismatch.
Debugging third-party API failures
Look up an unexpected status code (502, 504, 524) to diagnose what part of the request chain failed.
Writing API client retry logic
Identify which codes are safe to retry: 408, 429, 502, 503, 504 generally yes; 4xx other than 408/429 generally no.
Auditing security responses
Check that authentication failures return 401 (with WWW-Authenticate) and authorization failures return 403.
Server log analysis
Decode status codes when reading nginx/Apache logs to spot 502 spikes (upstream issues) or 429 storms (rate-limit abuse).
Documentation writing
Reference the exact name and intended use of a status code when writing API documentation.
Last updated: