tool / 42

HTTP Status Codes

Every status code that matters, with plain-English meaning.

All local
38/38
1xx Informational3
100
Continue

Server received headers, client should send body.

when to use
Used with `Expect: 100-continue` so a client can ask permission before uploading a large body.
101
Switching Protocols

Server agrees to switch protocols.

when to use
Sent during a WebSocket handshake when upgrading from HTTP/1.1 to the WebSocket protocol.
103
Early Hints

Preload hints sent before the final response.

when to use
A CDN sends `103 Early Hints` with `Link: </app.css>; rel=preload` so the browser can fetch CSS in parallel with rendering the page.
2xx Success5
200
OK

Standard success response.

when to use
`GET /users/42` returns the user object. The default for any successful read.
201
Created

Resource was created. Should return Location header.

when to use
`POST /users` creates a new user, returns `201` with `Location: /users/42` and the new resource in the body.
202
Accepted

Request accepted but processing not yet complete.

when to use
`POST /reports/generate` queues a long-running job. Returns `202` with a polling URL.
204
No Content

Success, but no body to return.

when to use
`DELETE /users/42` succeeds. There's nothing meaningful to return — `204` with empty body.
206
Partial Content

Range request — only part of the resource returned.

when to use
Video player sends `Range: bytes=0-1023`. Server returns `206` with the first 1KB so playback can start before the file finishes downloading.
3xx Redirection6
301
Moved Permanently

Resource has a new permanent URL.

when to use
Old blog at `/posts/123` permanently moved to `/blog/post-slug`. Returns `301` with `Location: /blog/post-slug`. SEO-friendly.
302
Found

Temporary redirect — original URL should still be used.

when to use
Showing a maintenance page temporarily. Use `302` not `301` so search engines don't update their index.
303
See Other

POST/PUT response should redirect to GET.

when to use
After `POST /orders`, redirect with `303` to `GET /orders/42` so a refresh doesn't re-submit the form (Post/Redirect/Get pattern).
304
Not Modified

Cached version is still valid.

when to use
Browser sends `If-None-Match: "etag-abc"`. Server hasn't changed it, returns `304` with no body. Saves bandwidth.
307
Temporary Redirect

Like 302 but preserves the HTTP method.

when to use
`POST /api/v1/users` is temporarily routed to `/api/v2/users`. `307` keeps the method as POST (302 would change it to GET).
308
Permanent Redirect

Like 301 but preserves the HTTP method.

when to use
API v1 retired. `POST /v1/users` returns `308` to `/v2/users` so existing clients continue to POST instead of breaking with a GET.
4xx Client Error18
400
Bad Request

Request was malformed.

when to use
Client sent `{invalid json` to a JSON endpoint. Or required `name` field is missing. Generic catch-all for client mistakes.
401
Unauthorized

Authentication required or failed.

when to use
Missing or expired token. Returns `401` with `WWW-Authenticate: Bearer realm="api"`. The client should re-auth and retry.
402
Payment Required

Reserved for future use.

when to use
Some SaaS APIs use it: free tier exceeded, upgrade to paid plan. Stripe uses it for failed-payment scenarios.
403
Forbidden

Authenticated but not allowed.

when to use
Logged-in user tries to access another user's data. They're identified — they just don't have permission. Don't retry.
404
Not Found

Resource doesn't exist.

when to use
`GET /users/9999999` — no such user. Also commonly returned in place of 403 to avoid leaking that a resource exists.
405
Method Not Allowed

Endpoint exists but doesn't accept this method.

when to use
`DELETE /reports` when only `GET` and `POST` are supported. Server should include `Allow: GET, POST` header.
406
Not Acceptable

Server can't produce a response matching Accept headers.

when to use
Client sends `Accept: application/xml` but the server only produces JSON. `406` says "I can't satisfy that".
408
Request Timeout

Server timed out waiting for the request.

when to use
Client opened a connection but stopped sending data. After N seconds the server gives up with `408`.
409
Conflict

Request conflicts with current state.

when to use
`POST /users` with an email that already exists. Or a `PUT` based on a stale ETag (optimistic concurrency conflict).
410
Gone

Resource permanently deleted.

when to use
Old API endpoint removed for good. Tells clients (and crawlers) to stop asking — different from 404 which implies "maybe later".
413
Payload Too Large

Request body exceeds server limit.

when to use
Trying to upload a 50MB file when the API caps at 10MB. The server cuts you off with `413`.
415
Unsupported Media Type

Server doesn't accept the Content-Type.

when to use
Sending `Content-Type: text/csv` to a JSON-only endpoint. The server can't parse it.
418
I'm a Teapot

April Fools joke from RFC 2324 (1998).

when to use
Some APIs (and Google) use it intentionally for fun. Not for serious use, but Cloudflare returns it for some blocked requests.
422
Unprocessable Entity

Well-formed but semantically wrong (validation failed).

when to use
JSON parsed fine, but `email: "not-an-email"` and `age: -5`. Return `422` with a list of field-level errors.
423
Locked

Resource is locked.

when to use
WebDAV: another user has a lock on the file you're trying to edit. Wait or steal the lock.
425
Too Early

Server unwilling to risk processing a possibly replayed request.

when to use
Used with TLS 1.3 0-RTT data. The server says "this is replay-prone, send it again over a fresh handshake".
429
Too Many Requests

Rate limited.

when to use
Client made 100 requests in 60 seconds — over the limit. Server returns `429` with `Retry-After: 30`.
451
Unavailable For Legal Reasons

Censored or legally restricted (1984 reference).

when to use
Content blocked in the user's country due to a court order or DMCA takedown. Tells the client *why* the resource can't be returned.
5xx Server Error6
500
Internal Server Error

Generic server error.

when to use
Something broke and we don't know what. An unhandled exception in your code. Don't return this for client errors — pick a 4xx.
501
Not Implemented

Server doesn't support the functionality.

when to use
Client sends `PROPFIND` (a WebDAV method) to a regular HTTP server. Server doesn't know what that is — `501`.
502
Bad Gateway

Upstream server returned an invalid response.

when to use
Your nginx/CDN proxies to your app server, but the app crashed and sent garbage. Reverse proxy returns `502`.
503
Service Unavailable

Server temporarily down.

when to use
Maintenance window, deploy in progress, or overloaded. Should include `Retry-After`. Use this instead of 500 when it's transient.
504
Gateway Timeout

Upstream server didn't respond in time.

when to use
CDN waited 60 seconds for your origin server to respond. It didn't. Returns `504`.
511
Network Authentication Required

Captive portal — must authenticate to access network.

when to use
Hotel/airport WiFi: any HTTP request gets `511` until you sign in to the portal page.