HTTP Status Codes Explained: A Developer's Reference

HTTP status codes are three-digit numbers grouped into five classes by their first digit:

• 1xx — Informational: the request is being processed.
• 2xx — Success: the request was received, understood, and accepted.
• 3xx — Redirection: further action is needed to complete the request.
• 4xx — Client error: the request has an error that the client must fix.
• 5xx — Server error: the server failed to fulfill a valid request.

200 OK — The standard success response. GET requests return 200 with the requested resource. PUT and PATCH may also return 200 with the updated resource.

201 Created — A new resource was created. POST requests that create a record should return 201, usually with a Location header pointing to the new resource.

204 No Content — The request succeeded but there is no body to return. Used for DELETE and sometimes PUT when the response body would be empty.

206 Partial Content — Used for range requests (chunked file downloads, video streaming). The response body contains only the requested byte range.

301 Moved Permanently — The resource has a new permanent URL. Search engines update their index. Browsers cache the redirect indefinitely. Use for permanent URL changes (HTTP to HTTPS, domain migrations).

302 Found — Temporary redirect. Browsers follow it but do not cache it. The original URL is still the canonical one. Often misused when 301 or 307 would be more semantically correct.

304 Not Modified — Used with caching. The server tells the client its cached copy is still fresh — no body is returned. Triggered by If-None-Match / If-Modified-Since headers.

307 Temporary Redirect — Like 302 but guarantees the method is preserved (a POST stays a POST). Use 307 instead of 302 for non-GET redirects.

308 Permanent Redirect — Like 301 but preserves the method. Use instead of 301 when redirecting POST or PUT requests permanently.

400 Bad Request — The server cannot process the request because of a client-side error: malformed syntax, invalid parameters, missing required fields.

401 Unauthorized — Authentication is required and was not provided or failed. Despite the name, this means "unauthenticated." Return 401 when no credentials are present or they are invalid.

403 Forbidden — The client is authenticated but does not have permission to access the resource. Return 403 when a valid user tries to access something they are not allowed to.

404 Not Found — The resource does not exist at the requested URL. Also used intentionally to hide resource existence from unauthorized users.

405 Method Not Allowed — The HTTP method is not supported for this endpoint (e.g., sending DELETE to a read-only endpoint). The response must include an Allow header listing supported methods.

409 Conflict — The request conflicts with the current state of the resource (e.g., duplicate creation, concurrent edit conflict).

422 Unprocessable Entity — The request is syntactically valid but semantically incorrect (e.g., validation errors in an otherwise well-formed JSON body). Widely used by REST APIs for field validation errors.

429 Too Many Requests — Rate limit exceeded. The response typically includes a Retry-After header with the wait time.

500 Internal Server Error — A generic catch-all for unhandled server-side exceptions. Check server logs for the root cause — the response body rarely contains the actual error in production.

502 Bad Gateway — A proxy or load balancer received an invalid response from an upstream server. Common during deploys when the upstream is momentarily unavailable.

503 Service Unavailable — The server is temporarily unable to handle requests (overload, maintenance). Use this with a Retry-After header when you know recovery time.

504 Gateway Timeout — The proxy timed out waiting for a response from the upstream server. Often seen during slow database queries or long-running background jobs that exceed the gateway timeout.

These two are commonly confused:

• 401 = "Who are you?" — no valid authentication credentials were provided.
• 403 = "I know who you are, but you cannot access this." — authenticated but not authorized.

The correct code matters for API consumers: 401 tells them to re-authenticate or provide credentials; 403 tells them authentication succeeded but they need different permissions.