Important Status Codes for REST API Development
Important Status Codes for REST API Development
HTTP status codes tell the client what happened after sending a request to the API.
For REST API development, you don't need to memorize every HTTP status code. Focus on the ones you will actually use in real projects.
1. 200 — OK
The request was successful.
Example: Successfully getting user data.
GET /users → 200 OK
2. 201 — Created
A new resource was successfully created.
Example: Creating a new user.
POST /users → 201 Created
3. 204 — No Content
The request was successful, but the server has nothing to return.
Example: Successfully deleting a user.
DELETE /users/10 → 204 No Content
4. 400 — Bad Request
The request sent by the client is invalid.
Example: Missing or incorrectly formatted data.
400 Bad Request
5. 401 — Unauthorized
The client has not provided valid authentication credentials.
Example: Missing or invalid login token.
401 Unauthorized
6. 403 — Forbidden
The client is authenticated but does not have permission to perform the action.
Example: A normal user tries to access an admin-only API.
403 Forbidden
7. 404 — Not Found
The requested resource does not exist.
Example:
GET /users/999
→ 404 Not Found
8. 405 — Method Not Allowed
The endpoint exists, but the HTTP method being used is not supported.
Example:
DELETE /users
when the endpoint only supports GET.
405 Method Not Allowed
9. 409 — Conflict
The request conflicts with the current state of the resource.
Example: Trying to create an account using an email that already exists.
409 Conflict
10. 422 — Unprocessable Content
The server understands the request, but the submitted data fails validation.
This is particularly important in FastAPI.
Example:
{
"age": "hello"
}
when the API expects age to be an integer.
422 Unprocessable Content
11. 429 — Too Many Requests
The client has sent too many requests in a certain period.
Example:
100 requests/minute allowed
↓
Client sends 150
↓
429 Too Many Requests
12. 500 — Internal Server Error
Something unexpected went wrong on the server.
Example: An unhandled exception occurs in your FastAPI application.
500 Internal Server Error
13. 502 — Bad Gateway
A gateway or proxy received an invalid response from another server.
Example:
Client
↓
API Gateway
↓
Backend Server
❌
502 Bad Gateway
14. 503 — Service Unavailable
The server is temporarily unable to handle requests.
Common reasons:
- Server maintenance
- Server overloaded
- Service temporarily down
503 Service Unavailable
15. 504 — Gateway Timeout
A gateway or proxy waited too long for another server to respond.
Client
↓
Gateway
↓
Backend
⏳ Too slow
504 Gateway Timeout
| Code | Meaning | Simple Meaning |
|---|---|---|
| 200 | OK | Success |
| 201 | Created | New data created |
| 204 | No Content | Success, nothing to return |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Authentication problem |
| 403 | Forbidden | Permission denied |
| 404 | Not Found | Resource doesn't exist |
| 405 | Method Not Allowed | Wrong HTTP method |
| 409 | Conflict | Conflict with existing data |
| 422 | Unprocessable Content | Validation failed |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
| 502 | Bad Gateway | Upstream server problem |
| 503 | Service Unavailable | Server unavailable |
| 504 | Gateway Timeout | Upstream server too slow |
Comments