HTTP Status Codes: Complete Reference for Developers

The Five Classes

HTTP status codes are three-digit integers grouped into five ranges by their first digit:

1xx — Informational

Rarely seen in application code but important in HTTP/2 and WebSocket upgrades:

100 Continue — The server has received the request headers and the client should proceed to send the request body. Used when clients send Expect: 100-continue before uploading large payloads.

101 Switching Protocols — The server is switching to the protocol requested in the Upgrade header. This is how WebSocket connections are established — the initial HTTP handshake ends with a 101.

2xx — Success

200 OK — The standard success response. The response body contains the requested resource.

201 Created — A new resource was created. Always include a Location header pointing to the new resource. Use this for POST requests that create records.

HTTP/1.1 201 Created
Location: /api/users/456
Content-Type: application/json

202 Accepted — The request was received and will be processed asynchronously. Use this when work is queued but not yet complete (e.g., email sends, video transcoding jobs, background data exports).

204 No Content — Success, but no body. The correct response for DELETE requests and PUT operations that don't return the updated resource.

206 Partial Content — Used with Range requests for large file downloads. Streaming video players use this to download content in chunks.

3xx — Redirection

301 Moved Permanently — The resource has permanently moved to the URL in the Location header. Search engines transfer all ranking signals to the new URL. Use this for permanent URL changes during site migrations.

302 Found — Temporary redirect. Search engines keep ranking the original URL. Use this for A/B testing redirects, maintenance pages, and login redirects.

303 See Other — After a POST, redirect to a GET endpoint. The standard pattern for POST-Redirect-GET (PRG), which prevents form resubmission on browser back/refresh.

304 Not Modified — The cached version of the resource is still valid. Sent in response to conditional requests (If-None-Match, If-Modified-Since). The browser uses its cache instead of downloading again.

307 Temporary Redirect — Like 302, but the HTTP method must not change. A POST to a URL returning 307 should POST to the redirect target, not GET.

308 Permanent Redirect — Like 301, but the HTTP method must not change. Use this instead of 301 when you need to permanently redirect a POST endpoint.

SEO implication: always use 301 (or 308 for non-GET) for permanent moves. A 302 on a URL that has been "temporarily" redirected for years is a common SEO mistake — Google won't consolidate signals to the new URL.

4xx — Client Errors

400 Bad Request — Generic client error. The server couldn't understand the request due to malformed syntax. Too vague for modern APIs — prefer more specific codes.

401 Unauthorized — Authentication required (despite the name — HTTP spec uses "unauthorized" to mean "unauthenticated"). The client should authenticate and retry. Include a WWW-Authenticate header indicating the authentication scheme.

403 Forbidden — Authenticated but not authorized. The server understood the request but refuses to act on it. Don't expose which resources exist to unauthorized users — return 404 instead of 403 when resource enumeration is a concern.

404 Not Found — Resource doesn't exist. Also the correct response when you want to hide a resource from unauthorized users (as above).

405 Method Not Allowed — The HTTP method isn't allowed on this endpoint. Always include an Allow header listing valid methods. A DELETE /users when only GET and POST are supported.

409 Conflict — Request conflicts with current state. Classic use case: trying to create a user with an email that already exists.

410 Gone — Resource existed but has been permanently deleted. Different from 404 — tells crawlers to remove the URL from their index. Use this for intentionally removed content.

422 Unprocessable Entity — Syntactically valid request but semantically wrong. The right code for validation errors: required field missing, value out of range, wrong data type. Follow RFC 7807 (Problem Details) format:

{
  "type": "https://example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    { "field": "email", "message": "Invalid email format" },
    { "field": "age", "message": "Must be 18 or older" }
  ]
}

429 Too Many Requests — Rate limit exceeded. Always include Retry-After header with the number of seconds to wait. Also include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

400 vs 401 vs 403 vs 422 — the confusion matrix:

5xx — Server Errors

500 Internal Server Error — Unhandled exception on the server. Log the full error server-side, return a generic message to the client. Never expose stack traces in production responses.

502 Bad Gateway — The server (acting as a gateway) received an invalid response from an upstream server. Common with reverse proxies (Nginx, load balancers) when your application crashes or returns garbage.

503 Service Unavailable — Server temporarily unable to handle requests — overloaded or down for maintenance. Include a Retry-After header. Used by load balancers when no healthy backend instances are available.

504 Gateway Timeout — The upstream server didn't respond in time. Common in microservice architectures when a dependency is slow. Distinguish from 503: 503 means the server refused; 504 means it didn't respond at all.

504 vs 502: Both are gateway errors. 502 means the upstream responded with garbage; 504 means it didn't respond within the timeout.

Designing Better API Error Responses

A bare status code isn't enough for client developers to act on. Implement RFC 7807 (Problem Details for HTTP APIs) — it's the standard format:

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 402,
  "detail": "Your balance of $10.00 is below the required $49.99.",
  "instance": "/transactions/txn_abc123"
}

The type URI should resolve to documentation explaining the error. The instance URI identifies the specific request that failed. This format is machine-readable and human-understandable simultaneously.

Use our API Error Generator to design and preview RFC 7807 error payloads for your API. Test the actual HTTP responses your server returns with our cURL Generator — pipe the output through our JSON Formatter to inspect response bodies clearly.

Status Codes in Caching

Status codes affect how proxies and browsers cache responses:

Setting Cache-Control: no-store overrides this for any code. Understanding which codes are cached by default prevents surprising stale responses in CDN-heavy architectures.