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.
💡 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. |