DevKit

HTTP Status Codes

A searchable reference for every HTTP status code, with the reasoning behind each one.

Free No sign-up Runs in your browser
Reference
60 codes

1xx — Informational

The request was received and processing continues.

100 Continue The server received the request headers and the client should send the body.
101 Switching Protocols The client asked to switch protocols (usually to WebSocket) and the server agreed.
102 Processing WebDAV: the server is working on the request and has not produced a response yet.
103 Early Hints Lets the server send Link headers before the final response, so the browser can preload assets.

2xx — Success

The request was received, understood and accepted.

200 OK The request succeeded. The body carries the representation.
201 Created A resource was created. The Location header should point at it.
202 Accepted The request was accepted for processing but is not finished — typical for async jobs.
203 Non-Authoritative Information The response came via a transforming proxy and is not the origin server's exact bytes.
204 No Content Success with no body. Common for DELETE and for PUT that changes nothing worth returning.
205 Reset Content The client should reset the document view, for example clear a form.
206 Partial Content A range request succeeded. Used for resumable downloads and video seeking.
207 Multi-Status WebDAV: the body contains separate status codes for several sub-requests.
208 Already Reported WebDAV: this resource was already listed in an earlier part of the multistatus response.
226 IM Used The response is the result of applying one or more instance manipulations (delta encoding).

3xx — Redirection

Further action is needed to complete the request.

300 Multiple Choices Several representations exist; the client or user picks one. Rarely used in APIs.
301 Moved Permanently The resource now lives at a new URL. Clients should update bookmarks and links.
302 Found Temporary redirect. Historically browsers changed POST to GET — use 307 to preserve the method.
303 See Other The result is at another URL; the client should fetch it with GET. The correct response after a POST-redirect-GET.
304 Not Modified The cached copy is still valid. Sent in reply to a conditional request with ETag or If-Modified-Since.
307 Temporary Redirect Temporary redirect that preserves the method and body, unlike 302.
308 Permanent Redirect Permanent redirect that preserves the method and body, unlike 301.

4xx — Client Error

The request contains an error the client can usually fix.

400 Bad Request The request is malformed — bad JSON, missing field, wrong type. The client should not retry unchanged.
401 Unauthorized Authentication is missing or invalid. Despite the name, it is about identity; include a WWW-Authenticate header.
402 Payment Required Reserved for future use; some APIs use it for quota or billing blocks.
403 Forbidden The server understood the request and refuses it. Authenticated but not allowed.
404 Not Found No resource at this URL. Also used deliberately to avoid revealing that a resource exists but is private.
405 Method Not Allowed The URL exists but not for this method. The Allow header must list the supported ones.
406 Not Acceptable The server cannot produce a representation matching the Accept headers.
407 Proxy Authentication Required The client must authenticate with the proxy first.
408 Request Timeout The client did not finish sending the request in time. The server may close the connection.
409 Conflict The request conflicts with the current state — a duplicate unique key, or a stale version in optimistic locking.
410 Gone The resource existed and was deliberately removed. More permanent and specific than 404.
411 Length Required The request must include a Content-Length header.
412 Precondition Failed A conditional header such as If-Match did not hold — often a lost update.
413 Content Too Large The body exceeds the server limit. Usually adjustable at the proxy or app server.
414 URI Too Long The URL exceeds what the server will parse. A sign to move data into the body.
415 Unsupported Media Type The Content-Type is not supported — commonly a missing application/json header.
416 Range Not Satisfiable The requested byte range lies outside the resource.
417 Expectation Failed The Expect header could not be met.
418 I'm a Teapot An April Fools' joke from RFC 2324 that became a beloved convention for "refusing on purpose".
421 Misdirected Request The request reached a server that cannot answer for this authority — common with HTTP/2 connection reuse.
422 Unprocessable Content Syntactically valid but semantically wrong: a validation error. Widely used by REST APIs.
423 Locked WebDAV: the resource is locked by another principal.
424 Failed Dependency WebDAV: the request failed because a related request failed.
425 Too Early The server refuses to process a replayable request to avoid a replay attack during the TLS handshake.
426 Upgrade Required The client must switch to a different protocol, usually TLS.
428 Precondition Required The server requires a conditional request to avoid lost updates.
429 Too Many Requests Rate limit exceeded. Include Retry-After so clients can back off correctly.
431 Request Header Fields Too Large Headers exceed the server limit — often an oversized cookie.
451 Unavailable For Legal Reasons Blocked for legal reasons, such as a court order or geo-restriction.

5xx — Server Error

The server failed to fulfil an apparently valid request.

500 Internal Server Error An unexpected condition prevented handling. Do not leak stack traces to the client.
501 Not Implemented The server does not support the functionality required — an unknown method, for instance.
502 Bad Gateway A proxy or gateway received an invalid response from the upstream server. Usually the app behind nginx is down.
503 Service Unavailable Temporarily overloaded or in maintenance. Add Retry-After when you know how long.
504 Gateway Timeout The upstream server did not respond in time. Increasing the proxy timeout or fixing the slow query is the real fix.
505 HTTP Version Not Supported The server does not support the HTTP version used in the request.
507 Insufficient Storage WebDAV: the server cannot store the representation — out of disk or quota.
508 Loop Detected WebDAV: an infinite loop was found while processing the request.
510 Not Extended Further extensions to the request are required for the server to fulfil it.
511 Network Authentication Required The client must authenticate to gain network access — the classic hotel or airport Wi-Fi page.

How to read the first digit

The three-digit code is structured: the first digit names the class, the other two are arbitrary within it. That is why a client can handle an unknown code sensibly just by its class.

  • 1xx — informational. The server is acknowledging and still working; these never appear as a final response body.
  • 2xx — success. The request was handled; the body (if any) carries the result.
  • 3xx — redirection. The client must take another step, usually to a different URL.
  • 4xx — the client made a mistake: bad syntax, missing credentials, insufficient permission, too many requests.
  • 5xx — the server failed. The request was probably fine; retrying later may work.

That distinction is the basis of sane retry logic: retry 5xx and 429 with backoff, never retry a 400 unchanged, and treat 501 as a deployment problem rather than a client one.

The confusions that actually cost time

401 vs 403

401 Unauthorized means "I do not know who you are" — credentials are missing or invalid. 403 Forbidden means "I know who you are, and you may not do this". Returning 401 without a WWW-Authenticate header is a spec violation; returning 403 when the token simply expired sends clients down the wrong path.

404 vs 410

404 is "nothing here" — perhaps never was, perhaps moved. 410 is "this existed and was deliberately deleted". 410 lets search engines drop a URL faster, but it is a commitment: do not use it for content you might restore.

301 vs 302 vs 307 vs 308

301/308 are permanent, 302/307 temporary. The numeric pairs differ in method handling: 301 and 302 historically let clients rewrite POST to GET, while 308 and 307 guarantee the method and body are preserved. For an API, choose 307/308; for a marketing URL change that is truly permanent, 301.

400 vs 422

400 means the request could not be parsed or is structurally invalid — malformed JSON, a missing required field. 422 means it parsed fine but failed validation — an end date before a start date, an unknown enum value. Many APIs use 400 for both; being precise makes client error handling much easier.

502 vs 503 vs 504

All three usually come from a reverse proxy, not your application. 502 means the upstream returned something unusable (often it crashed). 503 means the upstream is deliberately refusing (overload, maintenance). 504 means the upstream was too slow. The distinction tells you whether to look at crash logs, capacity, or a slow query.

Choosing a code is API design

Clients branch on status codes before they read the body, so the code is part of your contract. A few rules that hold up in practice: use 201 with a Location header on create, 204 on delete, 409 for uniqueness conflicts, 412 with ETags for optimistic concurrency, and 429 with Retry-After for rate limits. Put machine-readable detail in the body ({"error":"email_taken","field":"email"}) rather than inventing a new status code for every failure mode.

The codes you should not invent

Custom 4xx values outside the registered list confuse proxies, CDNs and client libraries — a CDN may cache a 200 that should have been an error, or strip a body from an unknown 4xx. If no standard code fits, pick the closest standard one and describe the problem in the payload.

Frequently asked questions

What is the difference between 401 and 403?
401 means authentication is missing or failed ("who are you?"); 403 means authentication succeeded but the action is not permitted ("I know you, and no").
Should I return 404 or 403 for a resource the user cannot see?
404 if revealing existence is itself a leak (private documents, other users' records). 403 when the resource is public knowledge and only the action is restricted.
Is 418 a real status code?
It is registered (RFC 2324, an April Fools' spec) and widely supported as an easter egg. Do not use it in a real API contract.
Which codes should a client retry automatically?
5xx and 429, with exponential backoff and jitter, and only for idempotent requests. Never retry a 4xx other than 408/429 without changing the request.
Do status codes affect SEO?
Yes. 301/308 pass ranking signals to the new URL, 302/307 do not transfer them the same way, 404 and 410 remove pages from the index, and 5xx on a live page can reduce crawl rate.

Related tools