HTTP Status Codes: The Complete Developer Reference

HTTP status codes are three-digit numbers returned by a server to describe the result of a request. Every HTTP response has one. Understanding what each code means is essential for debugging APIs, implementing error handling, and building correct web applications.

The Five Classes

Status codes are grouped into five classes by their first digit:

• 1xx — Informational: the request was received, processing continues
• 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 a problem the client can fix
• 5xx — Server error: the server failed to fulfil a valid request

The Most Important 2xx Codes

200 OK: the request succeeded. The response body contains the result. The standard success code for GET, POST, PUT, and most other methods.

201 Created: the request succeeded and a new resource was created. Use this for successful POST requests that create a new record. The response should include a Location header pointing to the new resource.

204 No Content: the request succeeded but there's nothing to return in the body. Appropriate for DELETE requests and PUT/PATCH operations when you don't want to return the updated resource.

The Most Important 3xx Codes

301 Moved Permanently: the requested resource has permanently moved to a new URL. Browsers and search engines cache this redirect and update their records. Use for permanent URL changes.

302 Found: temporary redirect. The resource is at a different URL right now but the original URL remains valid. Browsers follow the redirect but don't cache it.

304 Not Modified: the client sent a conditional request (with If-Modified-Since or If-None-Match), and the resource hasn't changed. The client should use its cached version. This is the browser cache working correctly.

The Most Important 4xx Codes

400 Bad Request: the server can't process the request because it's malformed. Common causes: invalid JSON body, missing required fields, malformed query parameters.

401 Unauthorized: authentication is required and has failed or hasn't been provided. Despite the name, this means "unauthenticated." Include a WWW-Authenticate header indicating the authentication scheme.

403 Forbidden: the client is authenticated but doesn't have permission to access the resource. This is the correct code when a logged-in user tries to access something they're not allowed to — not 401.

404 Not Found: the server can't find the requested resource. The most famous status code. Important distinction: return 404, not 403, when the existence of the resource would reveal sensitive information (which accounts exist, which files are present).

409 Conflict: the request conflicts with the current state of the resource. Common when trying to create a resource that already exists (duplicate email address on registration).

422 Unprocessable Entity: the request is well-formed but contains semantic errors. Often used by REST APIs instead of 400 for validation failures (the JSON is valid, but the field values don't make sense).

429 Too Many Requests: rate limit exceeded. The response should include a Retry-After header indicating when the client can retry.

The Most Important 5xx Codes

500 Internal Server Error: a generic server error. Something went wrong that wasn't caused by the request itself — an unhandled exception, a failed database query, a misconfiguration.

502 Bad Gateway: the server, acting as a gateway, received an invalid response from an upstream server. Common when a reverse proxy (nginx, Cloudflare) can't reach the application server.

503 Service Unavailable: the server is temporarily unable to handle requests — usually due to overload or maintenance. Include a Retry-After header.

504 Gateway Timeout: the gateway didn't receive a response from the upstream server within the timeout period. Similar to 502 but specifically a timeout rather than an invalid response.

For a complete interactive reference, see our HTTP Status Code Reference.