HTTP Status Code Reference

When the request itself is broken: malformed JSON, missing required parameter, invalid query string. Use 422 instead when the syntax is fine but the values fail business rules.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Invalid JSON: unexpected token at position 14"}

When no credentials were sent, the token is missing/expired/malformed, or the API key is invalid. Always include a WWW-Authenticate header indicating how to authenticate.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Content-Type: application/json

{"error":"Token expired","authUrl":"/login"}

Generally don't — it's reserved by the spec. If you need to signal billing issues, use 403 with a specific error message in the body.

User is authenticated but lacks permission — wrong role, accessing another user's data, attempting an admin-only action.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":"Insufficient permissions","required":"admin"}

Resource genuinely doesn't exist, or you want to hide its existence from unauthorized users (treating 403 as 404 for privacy).

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":"User not found"}

Client used the wrong method on a valid URL — e.g. POST to a read-only endpoint. Always include Allow header.

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD
Content-Type: application/json

{"error":"DELETE not supported on this resource"}

Rare. Client demanded a specific format (Accept: application/xml) you don't support. In practice most APIs ignore Accept and just return JSON.

HTTP/1.1 406 Not Acceptable
Content-Type: application/json

{"error":"Only application/json is supported","supportedTypes":["application/json"]}

Only from HTTP proxies — you wouldn't emit this from an application server.

Web server emits this automatically when the client opens a connection but stops sending data. You rarely write this manually.

POST creating a duplicate (e.g. username already taken), PUT with a stale ETag, deleting a resource that has dependents.

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":"Email already registered","conflictingResource":"/users/42"}

Deprecated API endpoints you've fully shut down, deleted user accounts you don't want re-created, old URLs you want removed from search engines.

HTTP/1.1 410 Gone
Content-Type: application/json

{"error":"This API was retired on 2026-01-01. Migrate to /v2/."}

Rare; HTTP/1.1 servers accept chunked transfer encoding instead. Only needed by some legacy systems.

PUT or PATCH where the client sent If-Match: "abc123" but the current ETag is different — someone else modified the resource since the client last read it.

HTTP/1.1 412 Precondition Failed
ETag: "def456"
Content-Type: application/json

{"error":"Resource modified by another request","currentEtag":"def456"}

File upload too big, JSON body over your size limit. Always document your size limits in your API docs — clients can't infer them.

HTTP/1.1 413 Content Too Large
Content-Type: application/json

{"error":"Maximum upload size is 10MB","received":52428800}

Almost never manually — your web server enforces this. If you're hitting it intentionally, switch the endpoint to POST with a body.

Client sent application/xml when you only handle JSON, or sent multipart form data to an endpoint that expects raw JSON. Include the supported types in the response.

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Accept: application/json

{"error":"Content-Type must be application/json"}

Automatically when you support Range requests and the client asks for bytes beyond end-of-file. Web server usually handles this.

Don't return it from a real API — it's a joke. Some bot-blocking systems use it for honeypot responses.

HTTP/1.1 418 I'm a teapot
Content-Type: text/plain

I'm a little teapot, short and stout.

Almost never from application code; emitted by load balancers and HTTP/2 servers handling multi-host connections.

Form validation failures: required field missing, value out of range, end-date-before-start-date, email already exists. The request was well-formed but rejected on its content.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{"errors":[{"field":"email","message":"Already taken"},{"field":"age","message":"Must be >= 18"}]}

Collaborative editing scenarios where only one user can write at a time. Most modern APIs use 409 Conflict or 423 with a custom body explaining who has the lock.

Batch APIs where step N failed because step N-1 failed. Most APIs handle this with their own error structure rather than this code.

Only relevant for TLS 1.3 0-RTT-enabled servers protecting against replay attacks. Library/server config concern, not application code.

When you've dropped support for older HTTP versions. Must include an Upgrade header listing what to switch to.

When an unconditional PUT/PATCH on a frequently-modified resource would risk overwriting concurrent edits. Forces clients to use If-Match with ETags.

HTTP/1.1 428 Precondition Required
Content-Type: application/json

{"error":"This endpoint requires If-Match header","example":"If-Match: \"abc123\""}

Always when rate-limiting. Always include Retry-After (seconds preferred). Including X-RateLimit-Remaining and X-RateLimit-Reset headers on regular responses helps clients self-throttle.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716552000
Content-Type: application/json

{"error":"Rate limit exceeded, retry in 60s"}

Almost never manually — your web server enforces header size limits. Often surfaces when cookies grow too large or auth tokens are appended to existing tokens.

Geoblocking by legal requirement, DMCA-takedown'd content, GDPR-erased resources. Should include a Link header pointing to information about the blocking authority.

HTTP/1.1 451 Unavailable For Legal Reasons
Link: <https://example.com/legal-notice>; rel="blocked-by"
Content-Type: application/json

{"error":"Unavailable in your region due to GDPR request"}