Status Code Classes
Status codes are grouped into five classes by their first digit:
| 1xx — Informational | Request received, processing continues |
|---|---|
| 2xx — Success | Request received, understood, and accepted |
| 3xx — Redirection | Further action needed to complete the request |
| 4xx — Client Error | The request contains bad syntax or cannot be fulfilled |
| 5xx — Server Error | The server failed to fulfil a valid request |
2xx — Success Codes
| 2xx Success | ||
|---|---|---|
| 200 OK | Standard success response | GET, PUT, PATCH responses with body |
| 201 Created | Resource successfully created | POST that creates a new resource; include Location header |
| 202 Accepted | Request accepted but not yet processed | Async operations — task queued, processing later |
| 204 No Content | Success, no response body | DELETE, or PUT/PATCH with no body returned |
| 206 Partial Content | Partial range of resource returned | Video streaming, file download resume (Range header) |
3xx — Redirect Codes
| 3xx Redirects | ||
|---|---|---|
| 301 Moved Permanently | Permanent redirect — cache it | Domain migrations, URL restructuring, SEO-safe redirect |
| 302 Found | Temporary redirect — don't cache | Login redirects, A/B testing, maintenance pages |
| 303 See Other | Redirect to GET after POST | Post-form-submit redirect (PRG pattern) |
| 304 Not Modified | Cached version is still valid | Browser sends If-Modified-Since; server confirms no change |
| 307 Temporary Redirect | Temp redirect, preserve method | Unlike 302, guarantees POST stays POST (not downgraded to GET) |
| 308 Permanent Redirect | Perm redirect, preserve method | Like 301 but method-preserving (POST stays POST) |
4xx — Client Error Codes
| 4xx Client Errors | ||
|---|---|---|
| 400 Bad Request | Malformed request | Invalid JSON, missing required fields, wrong data type |
| 401 Unauthorized | Authentication required | No token, expired token, invalid credentials |
| 403 Forbidden | Authenticated but not authorized | Regular user accessing admin endpoint |
| 404 Not Found | Resource does not exist | Wrong URL, deleted resource, ID not found |
| 405 Method Not Allowed | HTTP method not supported | PUT on a read-only endpoint |
| 409 Conflict | Request conflicts with current state | Duplicate email, version conflict, edit conflict |
| 410 Gone | Resource permanently deleted | Like 404, but explicitly communicates permanent removal |
| 422 Unprocessable Entity | Validation error | Invalid email format, date out of range, business rule violation |
| 429 Too Many Requests | Rate limit exceeded | Include Retry-After header indicating when to retry |
5xx — Server Error Codes
| 5xx Server Errors | ||
|---|---|---|
| 500 Internal Server Error | Unhandled exception | Application code crashed; always log these |
| 502 Bad Gateway | Invalid upstream response | App server crashed mid-response; proxy got garbage |
| 503 Service Unavailable | Temporarily unavailable | Overloaded or in maintenance; include Retry-After header |
| 504 Gateway Timeout | Upstream timeout | Proxy waited too long for app server; slow DB query |
Common Confusions Clarified
401 vs 403
- 401: "Who are you?" — not logged in, or credentials invalid
- 403: "I know who you are, but you can't do this" — authenticated but unauthorized
400 vs 422
- 400: Request is structurally wrong — missing field, invalid JSON, wrong content type
- 422: Request is structurally fine but data values fail validation — invalid email, future date required but past date given
301 vs 302
- 301: Permanent — browsers cache this, Google transfers page rank. Use for real URL changes.
- 302: Temporary — browsers do not cache. Use for login redirects, A/B tests.
💡 API Design Tip
Return consistent error bodies alongside your status codes: {"error": "VALIDATION_FAILED", "message": "email must be a valid email address", "field": "email"}. The status code tells clients what went wrong at a protocol level; the body gives actionable detail for debugging.
⚠️ Never Return 200 for Errors
Some older APIs return 200 OK with an error in the JSON body ({"success": false, "error": "..."}). This breaks HTTP clients, monitoring tools, and caches. Always use the correct 4xx or 5xx status code so standard tooling works correctly.
How We Research and Update This Guide
We test the underlying formula or workflow, compare outputs with reliable references, and revise examples whenever the page content changes.
- The workflow or formula is tested directly in the tool and compared against independent reference examples.
- Examples are kept practical so readers can verify the result without hidden assumptions.
- Pages are revised whenever the interface, calculation flow, or surrounding guidance materially changes.
Frequently Asked Questions — HTTP Status Codes
401 Unauthorized means the request lacks valid authentication credentials — the user is not logged in, or their token is expired/invalid. 403 Forbidden means the server understood the request and the user IS authenticated, but they do not have permission to access the resource. Example: 401 when you try to access an API without a token. 403 when you are logged in as a regular user and try to access an admin-only endpoint.
301 Moved Permanently tells the browser (and search engines) that the resource has permanently moved to the new URL. Browsers cache this redirect; search engines transfer SEO ranking to the new URL. 302 Found (temporary redirect) tells the browser the resource is temporarily at a different URL — do not cache it, do not transfer SEO ranking. Use 301 for permanent URL changes (domain migrations, removing www). Use 302 for A/B testing, login redirects, maintenance pages.
422 means the server understood the request format (valid JSON/XML) but the content failed validation. Example: you sent valid JSON with all required fields present, but the email field is not a valid email address, or a date is in the wrong format. 400 Bad Request is for malformed requests (invalid JSON, missing required fields). 422 is specifically for semantic validation failures — the structure is fine but the data values are invalid.
200 OK means the request succeeded and there is a response body. 204 No Content means the request succeeded but there is intentionally no response body. Use 204 for DELETE requests (nothing to return), or for PUT/PATCH when you choose not to return the updated resource. Do not use 204 for GET requests — a successful GET always has a body. Using 204 correctly reduces bandwidth and makes API intent clearer.
A 504 Gateway Timeout means a proxy or gateway (like Nginx or a load balancer) did not receive a timely response from an upstream server. The proxy itself is working, but the backend application server (Node.js, PHP, Python) is too slow or unresponsive. Common causes: a slow database query, an unresponsive external API call, or the backend server being overloaded. Unlike 503 (service unavailable), 504 specifically means the timeout happened at the proxy layer.
500 Internal Server Error: the application server itself threw an unhandled exception. 502 Bad Gateway: the proxy received an invalid response from the upstream server (e.g. the app server crashed mid-response). 503 Service Unavailable: the server is temporarily unable to handle requests — overloaded or in maintenance. 504 Gateway Timeout: the proxy timed out waiting for the upstream server to respond. 500 means your application code crashed; 502/503/504 are typically infrastructure-level issues.