200 OK
The request succeeded. The server returned the requested data.
When The standard response for a successful GET, PUT, or PATCH request.
Example GET /api/users/42 → 200 OK { "id": 42, "name": "Alice" }
HTTP Status Codes
Every important HTTP status code explained in plain English — what it means, when you'll see it, and a real-world example. Essential vocabulary for backend developers, QA engineers, and anyone who reads API logs.
Last reviewed:
💡 Common confusion: 401 vs 403
401 Unauthorized = "I don't know who you are." The client must authenticate (provide credentials).
403 Forbidden = "I know who you are — but you're not allowed to do this." The user is logged in but lacks permission.
The name "Unauthorized" for 401 is misleading — it actually means unauthenticated.
2xx Success
201 Created
A new resource was successfully created.
When Returned after a successful POST request that creates a new record.
Example POST /api/users → 201 Created — with a Location header pointing to the new resource.
204 No Content
The request succeeded, but there is no response body to return.
When Returned by DELETE requests or updates where no data needs to be sent back.
Example DELETE /api/users/42 → 204 No Content (empty body).
206 Partial Content
The server is delivering only part of the resource.
When Used when a client requests a specific byte range — common in video streaming.
Example GET /video.mp4 with Range: bytes=0-1023 → 206 Partial Content.
3xx Redirection
301 Moved Permanently
The resource has permanently moved to a new URL.
When Use when a page or endpoint is permanently relocated. Search engines update their index.
Example http://example.com → 301 → https://example.com (HTTP to HTTPS redirect).
302 Found
The resource is temporarily at a different URL.
When Temporary redirect — the client should keep using the original URL for future requests.
Example After a form submission, redirect to /success → 302 Found.
304 Not Modified
The resource has not changed since the client last fetched it — use your cached version.
When Returned when a conditional GET request (using If-Modified-Since or ETag) finds no new content.
Example GET /app.js with If-None-Match: "abc123" → 304 Not Modified (no body sent).
4xx Client Error
400 Bad Request
The server could not understand the request because of invalid syntax.
When Malformed JSON body, missing required fields, invalid query parameters.
Example POST /api/users with invalid JSON body → 400 Bad Request.
401 Unauthorized
The request requires authentication. The client must identify itself.
When Missing or invalid credentials (token expired, no Authorization header).
Example GET /api/account without a valid Bearer token → 401 Unauthorized.
Despite the name, this actually means "unauthenticated" — the user has not proved who they are.
403 Forbidden
The server understood the request but refuses to authorise it.
When The user is authenticated but lacks permission for this action.
Example DELETE /api/admin/users/1 by a regular-role user → 403 Forbidden.
401 = "Who are you?". 403 = "I know who you are — you are not allowed."
404 Not Found
The requested resource does not exist at this URL.
When Wrong path, deleted resource, typo in the URL, or resource ID does not exist.
Example GET /api/users/99999 → 404 Not Found.
405 Method Not Allowed
The HTTP method used is not supported for this endpoint.
When Calling POST on an endpoint that only accepts GET, or DELETE on a read-only resource.
Example POST /api/health → 405 Method Not Allowed (health check only supports GET).
409 Conflict
The request conflicts with the current state of the resource.
When Duplicate unique field (email already exists), optimistic lock conflict, or conflicting edit.
Example POST /api/users with email "alice@example.com" that already exists → 409 Conflict.
422 Unprocessable Entity
The request is well-formed, but the server cannot process it because of semantic errors.
When Validation errors — the JSON is valid but the field values fail business rules.
Example POST /api/orders with quantity: -5 → 422 Unprocessable Entity with field-level errors.
Preferred over 400 when the structure is valid but the content is logically invalid.
429 Too Many Requests
The client has sent too many requests in a given time window (rate limiting).
When Exceeded API rate limits. The response often includes Retry-After header.
Example 100 requests in 1 second to an API with a 60 req/min limit → 429 Too Many Requests.
5xx Server Error
500 Internal Server Error
Something went wrong on the server. The server encountered an unexpected condition.
When Unhandled exceptions, crashes, database errors, misconfigured environment.
Example An unhandled NullPointerException in the handler function → 500 Internal Server Error.
502 Bad Gateway
The server was acting as a gateway and received an invalid response from upstream.
When Common when Nginx/load balancer cannot reach the backend service.
Example Nginx forwards request to Node.js service that is down → 502 Bad Gateway.
503 Service Unavailable
The server is temporarily unable to handle the request.
When Server is overloaded, undergoing maintenance, or the downstream dependency is down.
Example Database is unreachable during a migration → 503 Service Unavailable.
504 Gateway Timeout
The server was acting as a gateway and did not receive a timely response from upstream.
When The backend service took too long to respond. Often a slow database query or external API.
Example API request times out waiting for a slow third-party payment service → 504 Gateway Timeout.
502 = upstream returned an error. 504 = upstream did not respond in time.
Quick Reference
| Code | Name | Plain English |
|---|---|---|
| 200 | OK | The request succeeded. The server returned the requested data. |
| 201 | Created | A new resource was successfully created. |
| 204 | No Content | The request succeeded, but there is no response body to return. |
| 206 | Partial Content | The server is delivering only part of the resource. |
| 301 | Moved Permanently | The resource has permanently moved to a new URL. |
| 302 | Found | The resource is temporarily at a different URL. |
| 304 | Not Modified | The resource has not changed since the client last fetched it — use your cached version. |
| 400 | Bad Request | The server could not understand the request because of invalid syntax. |
| 401 | Unauthorized | The request requires authentication. The client must identify itself. |
| 403 | Forbidden | The server understood the request but refuses to authorise it. |
| 404 | Not Found | The requested resource does not exist at this URL. |
| 405 | Method Not Allowed | The HTTP method used is not supported for this endpoint. |
| 409 | Conflict | The request conflicts with the current state of the resource. |
| 422 | Unprocessable Entity | The request is well-formed, but the server cannot process it because of semantic errors. |
| 429 | Too Many Requests | The client has sent too many requests in a given time window (rate limiting). |
| 500 | Internal Server Error | Something went wrong on the server. The server encountered an unexpected condition. |
| 502 | Bad Gateway | The server was acting as a gateway and received an invalid response from upstream. |
| 503 | Service Unavailable | The server is temporarily unable to handle the request. |
| 504 | Gateway Timeout | The server was acting as a gateway and did not receive a timely response from upstream. |
Frequently Asked Questions
What's the difference between 401 Unauthorized and 403 Forbidden?
401 means "I don't know who you are" — the request is missing valid credentials, so the client needs to authenticate. 403 means the server does know who you are but refuses the action anyway because you lack permission for it. The name "Unauthorized" for 401 is misleading; it really means unauthenticated.
What's the difference between 400 Bad Request and 422 Unprocessable Entity?
400 means the request itself is malformed — invalid JSON syntax, a missing required field structurally, or unparsable query parameters. 422 means the request is well-formed and syntactically valid, but the values fail business/validation rules, such as a negative quantity on an order — the JSON parses fine, the content is just logically invalid.
What's the difference between 301 Moved Permanently and 302 Found?
301 tells the client (and search engines) that the resource has permanently relocated, so they should update bookmarks and future requests to use the new URL — an HTTP-to-HTTPS redirect is a classic 301. 302 is a temporary redirect: the client should keep using the original URL for future requests, as is common after a form submission that briefly forwards to a success page.
What's the difference between 502 Bad Gateway and 504 Gateway Timeout?
Both occur when a server is acting as a gateway or proxy (e.g. Nginx in front of an app server). 502 means the upstream server returned an invalid or malformed response — or nothing was there to respond at all, as when the backend process is down. 504 means the upstream server never responded within the allowed time, typically because of a slow query or a slow third-party dependency.
When should an API return 200, 201, or 204?
200 OK is the standard success response for a GET, PUT, or PATCH that returns data. 201 Created is returned after a successful POST that creates a new resource, usually with a Location header pointing at it. 204 No Content is used when the request succeeded but there is nothing to send back in the body, such as after a DELETE.
How does a conditional GET request trigger a 304 Not Modified response?
The client sends a header like If-None-Match with the ETag it already has cached (or If-Modified-Since with a timestamp). If the server determines the resource has not changed, it returns 304 Not Modified with no response body, telling the client to keep using its cached copy — saving bandwidth compared to re-sending the full resource.
When does an API return 409 Conflict instead of 400 or 422?
409 Conflict specifically signals that the request conflicts with the current state of the resource on the server — for example, trying to create a user with an email address that already exists, or an optimistic-locking conflict where the resource changed since the client last read it. It is distinct from 400/422, which are about the request itself being malformed or invalid, not about a clash with existing server state.
What should a client do when it receives a 429 Too Many Requests?
A 429 means the client has exceeded the API's rate limit in the current time window. The response typically includes a Retry-After header specifying how many seconds (or an HTTP-date) to wait before trying again — well-behaved clients should honor that header and back off rather than immediately retrying.
What's the difference between 500 Internal Server Error and 503 Service Unavailable?
500 means the server hit an unexpected error while processing the request — an unhandled exception, a crash, or a misconfiguration in application code. 503 means the server is deliberately or temporarily unable to handle requests at all, such as during planned maintenance, an overload situation, or because a critical downstream dependency like the database is unreachable.
Is this HTTP status code reference free to use?
Yes — every status code, explanation, and example on this page is free to read and reference while you build or debug an API.