HTTP Status Codes

Selecting the right status code improves client behavior, caching efficiency, SEO, and observability. Pick the status class flowchart TD A[Request handled successfully] A -->|Yes| S[2xx] A -->|No| Q{Client problem} Q -->|Yes| C[4xx] Q -->|No| E[5xx] 2xx: the server accepted and completed the request. 4xx: the request is invalid or not allowed. 5xx: the server or an upstream failed to process a valid request. Success details: 200 vs 201 vs 202 vs 204 flowchart TD S[2xx] --> K{Created new resource} K -->|Yes| C201[201 Created] K -->|No| P{Processing deferred} P -->|Yes| C202[202 Accepted] P -->|No| B{Response body present} B -->|Yes| C200[200 OK] B -->|No| C204[204 No Content] 201 Created: resource was created; include a Location header. 202 Accepted: accepted for processing; finish later; provide a status endpoint or webhook if possible. 200 OK: success with a representation in the body. 204 No Content: success with no body to return. Conditional responses: 200 vs 304 flowchart TD P[Conditional request] P --> J{Representation changed} J -->|No| N304[304 Not Modified] J -->|Yes| N200[200 OK] 304 Not Modified: client can reuse its cached representation. 200 OK: representation changed or no valid validators. Authentication vs authorization: 401 vs 403 flowchart TD A[Access failed] --> X{Credentials present and valid} X -->|No| U401[401 Unauthorized] X -->|Yes| F403[403 Forbidden] 401 Unauthorized: include WWW-Authenticate with the challenge. 403 Forbidden: user is authenticated but not allowed. Validation vs business rules: 400 vs 422 flowchart TD V[Request invalid] V --> P{Syntax or schema malformed} P -->|Yes| B400[400 Bad Request] P -->|No| B422[422 Unprocessable Content] 400 Bad Request: malformed JSON, wrong types, missing required fields. 422 Unprocessable Content: syntactically valid but fails business rules or domain validation. Redirects See the dedicated guide: Redirects Deep Dive: 301 vs 302 vs 307 vs 308 ...

The 1xx class indicates the server has received the request headers and the client should proceed. Bodies are not returned. Most clients handle these automatically. Table of 1xx Codes Code Name Summary 100 Continue Client may send the request body. 101 Switching Protocols Protocol upgrade agreed (e.g., HTTP → WebSocket). 102 Processing Server has accepted the request, still working (WebDAV). 103 Early Hints Hints for preload before final response (RFC 8297). 100 Continue Used with Expect: 100-continue. Lets large uploads avoid sending a body if the server will reject the request. ...

The 2xx class means the request was successfully received, understood, and accepted. Table of 2xx Codes Code Name Summary 200 OK Standard success. 201 Created New resource created; Location may be set. 202 Accepted Processing deferred; result not yet available. 203 Non-Authoritative Information Metadata altered by a proxy. 204 No Content Success, no body. 205 Reset Content Client should reset the document view. 206 Partial Content Range response. 207 Multi-Status WebDAV multi-result. 208 Already Reported WebDAV deduplication of results. 226 IM Used Instance-manipulations applied. 200 OK General success. Caching: Cacheable by default for GET if headers permit. Pair with validators (ETag, Last-Modified) for efficient 304. ...

The 3xx class indicates the client must take additional action to complete the request. Table of 3xx Codes Code Name Summary 300 Multiple Choices Several representations available. 301 Moved Permanently Permanent redirect. 302 Found Temporary redirect (legacy semantics). 303 See Other Redirect to a different URI; use GET. 304 Not Modified Cached representation is still valid. 305 Use Proxy Deprecated. 306 (Unused) Reserved. 307 Temporary Redirect Temporary; method preserved. 308 Permanent Redirect Permanent; method preserved. 300 Multiple Choices Rarely used on the public web; content negotiation is usually implicit. ...

The 4xx class signals a problem with the client’s request. Use specific codes to help clients recover. Table of 4xx Codes (selected) Code Name Summary 400 Bad Request Malformed syntax or invalid parameters. 401 Unauthorized Requires authentication (send WWW-Authenticate). 403 Forbidden Understood but refused. 404 Not Found Resource does not exist. 405 Method Not Allowed Method not supported; send Allow. 406 Not Acceptable No acceptable representation. 408 Request Timeout Client took too long to send. 409 Conflict State conflict; e.g., versioning. 410 Gone Resource intentionally removed. 412 Precondition Failed ETag/If-* precondition failed. 415 Unsupported Media Type Content type not supported. 418 I’m a teapot Non-standard; avoid in production. 422 Unprocessable Content Semantically invalid data. 425 Too Early Retry-unsafe with early data. 429 Too Many Requests Rate limit exceeded. 431 Request Header Fields Too Large Headers too large. 451 Unavailable For Legal Reasons Blocked due to legal demands. 400 Bad Request Use for malformed JSON, invalid parameters, or schema violations. Include machine-readable error details. ...

The 5xx class indicates the server failed to fulfil an apparently valid request. These drive SLOs and on-call paging. Table of 5xx Codes (selected) Code Name Summary 500 Internal Server Error Generic server failure. 501 Not Implemented Method not supported at server. 502 Bad Gateway Upstream error at proxy/gateway. 503 Service Unavailable Overloaded or maintenance. 504 Gateway Timeout Upstream timeout. 507 Insufficient Storage WebDAV storage failure. 508 Loop Detected WebDAV loop. 510 Not Extended Further extensions required. 511 Network Authentication Required Captive portal/auth needed. 500 Internal Server Error Catch-all for unhandled exceptions. Log with correlation IDs; prefer specific 5xx when possible. ...

Redirects inform clients that a resource has moved. The choice of status code affects method handling, cache persistence, and search engine behaviour. Redirect Decision Flow flowchart TD A[Is the move permanent?] -->|Yes| B[Must the HTTP method be preserved?] A -->|No| C[Must the HTTP method be preserved?] B -->|Yes| D[308 Permanent Redirect] B -->|No| E[301 Moved Permanently] C -->|Yes| F[307 Temporary Redirect] C -->|No| G[302 Found] %% Contextual hints D:::perm --> H[Set long TTL; expect SEO consolidation] E:::perm --> H F:::temp --> I[Short TTL; use for maintenance] G:::temp --> I classDef perm fill:#ddd,stroke:#333,color:#000; classDef temp fill:#eee,stroke:#333,color:#000; Overview Table Code Meaning Method Preserved Cacheable by Default SEO Signal 301 Permanent redirect Not guaranteed Yes Passes link equity 302 Temporary redirect (legacy) Not guaranteed No Limited 307 Temporary, method preserved Yes No Limited 308 Permanent, method preserved Yes Yes Passes link equity 301 Moved Permanently Permanent relocation. Clients may update bookmarks. Caching: Long-lived; set deliberate TTL. ...