When should I return 4xx versus 5xx?
Return 4xx when the client can fix the request, credentials, or timing. Return 5xx when the request was reasonable but the server or an upstream dependency failed anyway.
Reference
HTTP Status Codes
Start here when you know whether the request succeeded, redirected, or failed, but you still need the code that matches what actually happened.
1xxInformational
Interim responses that indicate request progress before a final response is sent. Protocol handshakes, continue flows, and early rendering hints.
2xxSuccess
Responses indicating the request was accepted and processed successfully. Successful reads/writes where the request was accepted and processed.
- 200OKThe request succeeded and the response carries the result.
- 201CreatedA new resource was created; Location points to it.
- 202AcceptedAccepted for processing, but not finished yet.
- 203Non-Authoritative InformationA proxy modified the origin’s 200 response before passing it on.
- 204No ContentSuccess with no response body.
- 205Reset ContentSuccess; the client should reset the form or view that sent it.
- 206Partial ContentOnly the requested byte range is returned (Range requests).
- 207Multi-StatusWebDAVWebDAV: the body holds a separate status for each resource.
- 226IM UsedDelta encoding: the response is the result of instance manipulations.
3xxRedirection
Responses that tell clients to perform additional actions, usually by following a new URL. URL changes and canonical migrations that preserve user navigation.
- 300Multiple ChoicesSeveral representations exist; the client must choose.
- 301Moved PermanentlyThe resource moved permanently to a new URL.
- 302FoundTemporary redirect; keep using the original URL.
- 303See OtherFetch the result with GET at another URL.
- 304Not ModifiedCached copy is still valid; no body sent.
- 307Temporary RedirectTemporary redirect that preserves method and body.
- 308Permanent RedirectPermanent redirect that preserves method and body.
4xxClient error
Client-side request issues such as invalid syntax, missing resources, or permission failures. Client-side request issues like missing resources, invalid auth, or rate limits.
- 400Bad RequestThe server cannot parse or accept the malformed request.
- 401UnauthorizedValid credentials are missing or wrong; authenticate.
- 402Payment RequiredReserved for payment flows; rarely used consistently.
- 403ForbiddenIdentity is known, but this action is not allowed.
- 404Not FoundNo resource found at this URL.
- 405Method Not AllowedThe method is not allowed for this resource.
- 406Not AcceptableCannot produce a representation matching the Accept headers.
- 407Proxy Authentication RequiredThe proxy in between needs credentials before forwarding.
- 408Request TimeoutServer gave up waiting for the complete request.
- 409ConflictThe request conflicts with the resource current state.
- 410GoneThe resource is gone and will not come back.
- 411Length RequiredThe server refuses requests without a Content-Length.
- 412Precondition FailedA conditional header (If-Match, etc.) evaluated to false.
- 413Content Too LargeRequest body is larger than the server accepts.
- 414URI Too LongThe request URL is longer than the server accepts.
- 415Unsupported Media TypeThe request body media type is not supported.
- 416Range Not SatisfiableThe requested byte range is outside the resource’s size.
- 417Expectation FailedThe server can’t meet the request’s Expect header.
- 418I'm a teapotRFC 2324 (joke)RFC 2324’s joke teapot; sometimes used to reject bots.
- 419Page ExpiredLaravelLaravel: the CSRF token did not match the session (often an expired form).
- 421Misdirected RequestThe request reached a server that can’t answer for this host.
- 422Unprocessable ContentSyntax is valid but the content fails validation.
- 423LockedWebDAVWebDAV: the resource is locked.
- 424Failed DependencyWebDAVWebDAV: failed because an action it depended on failed.
- 425Too EarlyThe server won’t risk processing a replayable TLS early-data request.
- 426Upgrade RequiredThe client must upgrade to a different protocol.
- 428Precondition RequiredThe server requires a conditional request.
- 429Too Many RequestsRate limit hit; slow down and check Retry-After.
- 431Request Header Fields Too LargeRequest headers are too large.
- 444No Responsenginxnginx closed the connection without sending any response.
- 451Unavailable For Legal ReasonsBlocked for legal reasons.
- 460Client Closed ConnectionAWS ALBAWS ALB: the client closed the connection before the idle timeout.
- 463Too Many Forwarded IP AddressesAWS ALBAWS ALB: X-Forwarded-For contains more than 30 IP addresses.
- 464Incompatible Request ProtocolAWS ALBAWS ALB: request protocol conflicts with the target group protocol version.
- 497HTTP Request Sent to HTTPS Portnginxnginx: a plain HTTP request hit an HTTPS port (clients see a 400).
- 499Client Closed Requestnginxnginx log code: the client hung up before the response.
5xxServer error
Server-side failures where the request was valid but the server could not complete it. Server-side failures, upstream outages, and transient platform incidents.
- 500Internal Server ErrorUnexpected server failure with no more specific code.
- 501Not ImplementedThe server does not support this functionality.
- 502Bad GatewayA gateway got an invalid response from upstream.
- 503Service UnavailableServer is overloaded or down for maintenance.
- 504Gateway TimeoutA gateway timed out waiting for upstream.
- 505HTTP Version Not SupportedThe HTTP version in the request is not supported.
- 506Variant Also NegotiatesContent negotiation is misconfigured into a loop.
- 507Insufficient StorageWebDAVWebDAV: the server is out of storage.
- 508Loop DetectedWebDAVWebDAV: the server hit an infinite loop while processing.
- 509Bandwidth Limit ExceededcPanelcPanel hosting: the administrator-imposed bandwidth limit was reached.
- 510Not ExtendedAn HTTP extension the request needs isn’t supported (historic).
- 511Network Authentication RequiredLog in to the network first, e.g. a captive Wi-Fi portal.
- 520Web Server Returned an Unknown ErrorCloudflareCloudflare: origin returned an unexpected response.
- 521Web Server Is DownCloudflareCloudflare: the origin server refused the connection.
- 522Connection Timed OutCloudflareCloudflare: connecting to the origin timed out.
- 523Origin Is UnreachableCloudflareCloudflare: the origin is unreachable.
- 524A Timeout OccurredCloudflareCloudflare: the origin accepted but replied too slowly.
- 525SSL Handshake FailedCloudflareCloudflare: the TLS handshake with the origin failed.
- 526Invalid SSL CertificateCloudflareCloudflare: the origin’s certificate failed strict validation.
- 529Site Is OverloadedSSL Labs / AnthropicSSL Labs / Anthropic: the API is temporarily overloaded.
- 530Origin DNS ErrorCloudflareCloudflare: origin error, paired with a 1xxx error code.
- 561UnauthorizedAWS ALBAWS ALB: the identity provider returned an error during authentication.
No status codes match this filter.
Error-First Navigation
Start from the symptom when you do not yet know the exact code.
- 404
Broken or Missing Page
Start with 404 diagnostics for deleted routes, stale links, and typos.
- 401
Auth Required
Use 401 when credentials are missing or invalid; pair with WWW-Authenticate.
- 403
Permission Denied
Use 403 when identity is known but the action is not allowed.
- 429
Rate Limit Hit
Use 429 for throttling and communicate retry windows clearly.
- 500
Unhandled Server Error
Debug unknown origin failures and improve fallback behavior.
- 503
Temporary Outage
Signal maintenance or overload conditions with clear recovery hints.
How Status Codes Encode Outcome
Status codes are the shortest honest summary of what happened to a request. If your API returns the wrong one, clients retry the wrong thing, browsers behave differently, and debugging gets slower for everyone involved.
- 1xx informational
- Interim responses that keep the exchange moving before the final answer is ready, such as 100 Continue or 103 Early Hints.
- 2xx success
- The request worked. The details still matter, though: 200, 201, 202, and 204 all imply different follow-up expectations.
- 3xx redirection
- The client is not done yet. It needs another URL, a different method, or cached state before the flow is complete.
- 4xx and 5xx errors
- 4xx means the request is wrong for the current client context. 5xx means the server or one of its dependencies failed to complete valid work.
Use This Hub When The Outcome Is Clear But The Code Is Not
Most arguments about status codes happen when multiple answers sound plausible. This page helps narrow those cases down fast.
- Choose the code that matches the protocol outcome, not the wording of the exception in your app.
- Look at related headers too: Location, Retry-After, WWW-Authenticate, and Cache-Control often finish the story.
- Use class pages and the picker when the debate is between two valid-looking codes, not when you already know the answer.
Questions Teams Argue About
When should I use 401 instead of 403?
Use 401 when the request lacks valid credentials and the client can authenticate again. Use 403 when the identity is known but still not allowed to do the thing it asked for.
Why do redirects use different 3xx codes?
Because some redirects preserve the original method and body while others switch the follow-up request to GET. The distinction affects forms, APIs, caches, and browser behavior.