HTTP Status Codes.

The server has read the request headers and is willing to take the body. A final status still follows on the same request.

Use it when you never write it by hand. It exists so a client that sent Expect: 100-continue can avoid uploading two gigabytes before learning the request would be rejected.

The connection is leaving HTTP for whatever the Upgrade header named — in practice, WebSocket.

Use it when a protocol handshake, and only from the server side. Over HTTP/2 and HTTP/3 WebSockets use extended CONNECT instead, so you will never see a 101 there.

The server is still working on a long WebDAV operation and wants the client to keep waiting.

Use it when essentially never. It only ever applied to WebDAV, and 103 covers the useful half of the idea.

A preliminary response carrying Link headers so the browser can start fetching CSS, fonts, and scripts while the origin is still generating the real response.

Use it when your time-to-first-byte is dominated by slow server work and you know the critical assets up front. Cloudflare and Fastly can synthesise it for you; browsers only act on it for navigation requests.

The request succeeded and the body, if there is one, is the result.

Use it when the operation fully succeeded and you are handing back a representation. Not when it half-worked, and never with an error object inside.

A new resource now exists. The response should carry a Location header pointing at it, and usually the new representation as the body.

Use it when a POST or PUT created something addressable — POST /orders that returns order 1234. If nothing was created and you only queued work, that is a 202.

The request was valid and has been queued. Nothing has actually happened yet, and it might still fail.

Use it when async work: you enqueued a job, sent it to a worker, or handed it to a batch pipeline. Always return somewhere to poll — a Location header or a status URL in the body. A bare 202 tells the client nothing it can act on.

Success, but a transforming proxy in the middle modified the payload, so it is not exactly what the origin sent.

Use it when you are writing a proxy that rewrites responses. Applications do not emit this.

Success, and there is deliberately nothing to send. A 204 must not carry a body at all.

Use it when DELETE succeeded, a PUT saved with nothing worth returning, a preference toggle. Two traps: a browser navigating to a 204 stays on the current page, and fetch's response.json() throws on it. If the caller needs data, return 200 with a body instead.

Success, and the client should reset the form or document view that sent the request. Also forbidden from carrying a body.

Use it when almost never outside legacy form workflows. Modern front ends reset their own state.

Here is the byte range that was asked for. Requires a Content-Range header describing what was sent.

Use it when range requests — video seeking, resumable downloads, byte-serving PDFs. Your CDN and static file server do this; you rarely hand-write it.

One response body carrying a separate status for each of several resources.

Use it when WebDAV. It is also the honest answer for a batch endpoint where individual operations can fail independently — but if you invent your own envelope, do not label it 207.

Inside a 207 body: this resource was already enumerated earlier in the response, so it is not repeated.

Use it when WebDAV collections only.

The response is a delta against a version the client already has, per the instance-manipulation extension in RFC 3229.

Use it when practically never — almost nothing implements delta encoding.

Several representations exist and the client (or user) should pick one.

Use it when rarely worth the trouble. There is no standard machine-readable format for the choices, so agents cannot act on it.

This URL is gone for good; use the new one and update your links. Browsers and caches hold on to it hard — often for the life of the profile.

Use it when a permanent move you are certain about. Clients are allowed to rewrite a POST into a GET on a 301, and they do. If the method matters, use 308.

A temporary redirect. The original URL still owns the resource and should keep being used.

Use it when a genuinely temporary move. Most frameworks still emit 302 from their redirect() helper — and it inherits the POST-becomes-GET rewrite from 301, so for a form post-back 303 is the code that actually says what you mean.

Go and GET this other URL. Changing the method to GET is mandatory and intentional.

Use it when post/redirect/get — you processed a form and want a refresh not to resubmit it. Also correct for handing a client the result URL of a job it POSTed.

The cached copy the client already has is still fresh. No body is sent.

Use it when a conditional request with If-None-Match or If-Modified-Since matched. Send the validators and cache headers, not the payload — that is the whole point.

The resource must be fetched through the proxy named in the response.

Use it when never. Deprecated for security reasons and ignored by every current client.

Used in a draft, never standardised, and permanently reserved so nothing else can claim it.

Use it when never.

A temporary redirect where the method and the body must be preserved exactly.

Use it when you need to bounce a POST, PUT, or PATCH somewhere else without losing the body. This is the 302 you actually wanted on an API.

A permanent redirect where the method and the body must be preserved exactly.

Use it when a permanent move on an API where POST has to stay POST. Also the safer choice for http-to-https canonicalisation on endpoints that accept writes.

The server refuses to process the request because the request itself is wrong: unparseable JSON, a malformed query string, a missing required field.

Use it when the payload could not be understood or is structurally invalid. RFC 9110 widened 400 to cover any client error the server cannot classify better, so it is always defensible — but a more specific code is more useful to the caller.

Misnamed: it means unauthenticated. No credentials were supplied, or the ones supplied were not valid.

Use it when the client should authenticate and retry. It must carry a WWW-Authenticate header naming the scheme, and in practice that header is the single most commonly omitted requirement in the whole 4xx block.

Reserved since 1997 and quietly real now: Stripe returns it for declined cards, and metered APIs use it for an exhausted plan.

Use it when billing state blocks the call. There is no standard semantics behind it, so document exactly what you mean and what the client should do.

The server understood the request and is refusing to authorise it. Re-authenticating is not implied to help.

Use it when an authenticated caller lacks permission, or a WAF, IP allowlist, or policy engine blocked the request. If logging in would fix it, the correct code is 401.

There is no resource at that URL, and the server is not saying whether there ever was one.

Use it when a route does not exist, an ID does not resolve, or you are deliberately hiding the existence of something the caller has no right to know about. That last case is a legitimate and common substitute for 403.

The URL exists but that verb is not supported on it.

Use it when you route by method and this one is not wired up. The response must include an Allow header listing the methods that are — frameworks that skip it turn a five-second fix into a debugging session.

Nothing the server can produce matches the client's Accept header.

Use it when content negotiation genuinely fails and returning something anyway would be wrong. Most JSON APIs are better off ignoring a nonsense Accept header and serving JSON.

The 401 of the proxy world. The client must authenticate with the proxy, which sends Proxy-Authenticate.

Use it when you are a proxy. Seeing it as a client usually means a corporate egress proxy is in the path.

The client was too slow sending the request and the server is closing an idle connection.

Use it when you are a server reaping connections. As a client, a 408 is often just keep-alive housekeeping rather than a real error — retry the request once.

The request clashes with the current state of the resource.

Use it when a duplicate create hits a unique constraint, an edit lands on a stale version, or a delete is blocked by dependents. Say what conflicts in the body — a bare 409 is a support ticket waiting to happen.

It existed, it was deliberately removed, and it is not coming back.

Use it when you intentionally deleted something and want clients and crawlers to drop it. Search engines treat 410 as a slightly stronger removal signal than 404. Only reach for it when the removal really is permanent.

The request needs a Content-Length header and did not have one.

Use it when you cannot accept a chunked or length-less body on this endpoint.

A condition the client attached to the request — If-Match, If-Unmodified-Since — did not hold.

Use it when optimistic concurrency: the caller sent an ETag and the resource changed underneath them. This is how you stop lost updates without taking a lock.

The body exceeds what the server is willing to accept. Renamed from Payload Too Large in RFC 9110.

Use it when an upload is over the limit. Check the whole chain before blaming your code — nginx defaults client_max_body_size to 1 MB, and most managed gateways cap request bodies far below what your handler allows.

The request target is longer than the server will parse.

Use it when someone put a filter payload in a query string. It is usually a signal that the operation should have been a POST.

The Content-Type of the body is not one this endpoint accepts.

Use it when form-encoded data arrived at a JSON-only endpoint, or the Content-Type header is missing entirely. Most mysterious empty-body bugs deserve this instead of a vague 400.

The requested byte range does not exist in the representation.

Use it when you serve range requests and the range is out of bounds. Reply with Content-Range: bytes star-slash-length so the client learns the real size.

The server will not meet the expectation in the Expect header — in practice, Expect: 100-continue.

Use it when you are a server or proxy that refuses 100-continue.

A 1998 April Fools joke from RFC 2324. IANA keeps it reserved specifically so nothing real can ever claim it.

Use it when never in production. It is funny right up until a CDN, an SDK's error mapper, or an on-call engineer has to deal with it.

This connection cannot serve requests for that authority — HTTP/2 connection coalescing sent the request to the wrong origin.

Use it when you are terminating HTTP/2 for multiple hostnames on one certificate. The client is expected to retry on a fresh connection.

The syntax is fine and the body parsed, but the values are semantically unacceptable.

Use it when validation failed on a well-formed request — an end date before a start date, an email that is not an email. Return field-level errors in the body; RFC 9457 problem details is a ready-made shape for that.

The resource is locked by another party.

Use it when WebDAV locking, or a domain model with explicit checkouts.

This request was not attempted because a request it depended on failed.

Use it when WebDAV, and occasionally a batch pipeline where one step gates the next.

The request arrived in TLS 1.3 early data (0-RTT) and the server will not risk processing a replayable request.

Use it when you terminate TLS with 0-RTT enabled and the request is not idempotent. The client retries once the handshake completes. If you have never enabled 0-RTT, you will never emit this.

The endpoint requires a different protocol.

Use it when you refuse plain HTTP/1.1 on an endpoint that needs TLS or a newer version. Must include an Upgrade header naming what you want.

The server refuses an unconditional request and wants the client to send If-Match.

Use it when you want to force every writer to prove which version it is editing, so two concurrent updates cannot silently clobber each other. It is the polite half of the 412 story.

The client has exceeded a rate limit.

Use it when rate limiting or quota enforcement — and always with a Retry-After header, in seconds or as an HTTP date. Without it, well-behaved clients guess and badly-behaved ones hammer you. The RateLimit-* fields are still an IETF draft; Retry-After is the one everything already understands.

The headers, individually or in total, exceeded what the server will accept.

Use it when a cookie jar or a bloated JWT blew past the limit. Node defaults to 16 KB of headers; nginx to 8 KB buffers. Fix the token size, do not raise the ceiling.

Blocked because of a legal demand — a court order, a takedown, a sanctions regime — not a technical failure.

Use it when the law, not your policy, is the reason. Include a Link header with rel=blocked-by naming the entity making the demand. Generic geo-blocking with no legal basis is a 403.

Not in any RFC. Laravel returns it when the CSRF token is missing, stale, or the session expired.

Use it when you are debugging a Laravel form that suddenly stopped submitting. The fix is session lifetime or a refreshed token, not the status code.

Twitter's rate-limit code from before 429 existed. Retired, but still quoted in old client libraries.

Use it when never. Use 429.

Shopify's code for a request its edge security layer rejected before your app ever saw it.

Use it when you are reading Shopify app logs. It is not something you emit.

Microsoft IIS: the session expired and the client must authenticate again.

Use it when never by hand. Standard equivalent is 401.

An nginx directive that closes the connection without sending anything at all. It appears in the access log and never on the wire.

Use it when you are dropping abusive traffic at the edge without spending bytes on a response.

Microsoft IIS: retry the request after supplying more information.

Use it when never. It has no standard meaning.

The client disconnected before the AWS load balancer could send a response. Log-only, like nginx 499.

Use it when you are reading ALB access logs. It points at client timeouts or slow targets, not at the balancer.

The request arrived at an AWS load balancer with more than 30 addresses in X-Forwarded-For.

Use it when you are debugging a proxy chain that keeps appending. Fix the chain.

An nginx-internal code, logged when headers overflow the configured buffers.

Use it when never — nginx converts it to a 400 on the wire. Standard equivalent is 431.

nginx-internal: the client presented a certificate that failed verification.

Use it when never by hand. It shows up when you enable mutual TLS.

nginx-internal: mutual TLS is on and the client sent no certificate.

Use it when never by hand. Same family as 495.

nginx-internal: a plaintext request arrived on a TLS listener.

Use it when never by hand. Usually a misconfigured health check or an http:// URL that should be https://.

nginx writes this to its access log when the client hung up before a response was ready. It is never sent over the wire — nobody receives a 499.

Use it when you are reading nginx logs. A spike means callers are timing out first, so look at upstream latency and client timeouts, not at nginx. Esri's servers use 499 for a missing token, which is an unrelated collision.

Something in the server blew up and nothing more specific applies. It is a statement that the caller did nothing wrong.

Use it when an unhandled exception, a null dereference, a broken invariant. Every 500 should map to a log line with a stack trace. Never use it for validation — that is a 4xx, and mixing the two destroys your error budget.

The server does not support the method at all, anywhere — not merely on this URL.

Use it when a gateway meets a verb it has never heard of. If the method exists but not on this route, that is 405.

A proxy received an invalid, empty, or unparseable response from the server behind it.

Use it when you are the proxy. From outside, a 502 almost always means the app crashed, refused the connection, or wrote garbage — check the application logs, not the proxy's.

The service is temporarily unable to handle the request: overloaded, draining, starting up, or deliberately in maintenance.

Use it when the condition is temporary and you know roughly for how long — pair it with Retry-After. It is the only 5xx that clients, CDNs, and crawlers are meant to treat as transient, which is why a maintenance window should return 503 and never 500 or 404.

A proxy gave up waiting for the server behind it to respond.

Use it when you are the proxy and upstream blew the timeout budget. A 504 landing at exactly 30 or 60 seconds is a configuration value, not a mystery — compare the gateway timeout with the application's own.

The major HTTP version in the request is not supported.

Use it when practically never. Almost always a client speaking something that is not HTTP at all.

A transparent content negotiation misconfiguration on the server side.

Use it when never, unless you are implementing RFC 2295.

The server cannot store the representation needed to complete the request.

Use it when WebDAV, or an upload service that is genuinely out of disk. Mostly you want 503 with a Retry-After.

The server aborted an operation because it found an infinite loop.

Use it when WebDAV bindings. Its useful cousin in application code is a request-depth or recursion guard.

The request needs further extensions to be processed. The extension framework behind it was made historic.

Use it when never.

You are behind a captive portal that wants you to log in to the network.

Use it when you are the intercepting proxy — an origin server must never generate it. The entire point is that a client can tell apart the network hijacking the request and the API saying no.

An Apache and cPanel extension for an account over its transfer quota.

Use it when never in your own code. Use 429 or 503.

Cloudflare's catch-all: the origin returned something empty, malformed, or otherwise unintelligible.

Use it when you are debugging a Cloudflare-fronted site. It usually means the origin reset the connection or sent an invalid response — check the origin, not Cloudflare.

The origin actively refused Cloudflare's connection.

Use it when you are reading a Cloudflare error page. The origin process is down or its firewall is dropping Cloudflare's IPs.

The TCP handshake between Cloudflare and the origin never completed.

Use it when network-level diagnosis: routing, security groups, or an overloaded origin accept queue.

Cloudflare could not route to the origin at all — usually a bad DNS record or a dead IP.

Use it when check the DNS record behind the proxied hostname.

The origin accepted the connection but did not finish responding inside Cloudflare's window (100 seconds on the standard plans).

Use it when you have a long-running request behind Cloudflare. Move it to a job and return 202 rather than trying to raise the ceiling.

The TLS handshake between Cloudflare and the origin failed.

Use it when you set Full or Strict SSL mode and the origin's TLS config does not agree — ciphers, versions, or SNI.

The origin presented a certificate Cloudflare could not validate in Strict mode.

Use it when expired, self-signed, or wrong-hostname origin certificates. Install a real certificate or an origin certificate from Cloudflare.

A failure in Cloudflare's retired Railgun transport.

Use it when never — the product is gone. Included because it still turns up in old runbooks.

Always shown alongside a Cloudflare 1xxx error code; the real cause is in that number, most often a Worker exception or an origin DNS failure.

Use it when you see a 530 — go read the 1xxx code on the error page, because the 530 itself tells you nothing.

A convention some proxies and HTTP clients use for a connection timeout they invented themselves.

Use it when never in your own responses. It exists so client libraries have something to put in a log line.