HTTP methods, status code categories, common codes, and REST conventions
Retrieve a resource. Safe and idempotent. No request body.
GET /api/users/123
GET /api/posts?page=2&limit=10Create a new resource or trigger an action. Not idempotent.
POST /api/users
Content-Type: application/json
{ "name": "Alice", "email": "alice@example.com" }Replace a resource entirely. Idempotent.
PUT /api/users/123
{ "name": "Alice", "email": "new@example.com" }Partially update a resource. Not always idempotent.
PATCH /api/users/123
{ "email": "newemail@example.com" }Remove a resource. Idempotent.
DELETE /api/users/123HEAD returns headers only. OPTIONS lists allowed methods (CORS preflight).
HEAD /api/users/123 # get headers, no body
OPTIONS /api/users # allowed methodsRequest succeeded. Standard response for GET, PUT, PATCH.
HTTP/1.1 200 OK
{ "id": 1, "name": "Alice" }Resource was created successfully. Include Location header.
HTTP/1.1 201 Created
Location: /api/users/42
{ "id": 42, "name": "Alice" }Request succeeded but no response body. Use for DELETE.
HTTP/1.1 204 No Content
# No bodyResource has permanently moved. Browsers cache this.
HTTP/1.1 301 Moved Permanently
Location: https://new-domain.com/pageTemporary redirect. Client should use original URL next time.
HTTP/1.1 302 Found
Location: /loginCached version is still valid. No body returned.
HTTP/1.1 304 Not Modified
# Client should use its cached version307 = temporary redirect, preserves method. 308 = permanent, preserves method.
307 Temporary Redirect → preserves POST method
308 Permanent Redirect → preserves POST methodMalformed request syntax or invalid parameters.
HTTP/1.1 400 Bad Request
{ "error": "Invalid email format" }Authentication required or credentials invalid.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
{ "error": "Authentication required" }Authenticated but not authorized for this resource.
HTTP/1.1 403 Forbidden
{ "error": "Insufficient permissions" }Resource does not exist at this URL.
HTTP/1.1 404 Not Found
{ "error": "User 999 not found" }Request conflicts with current state (e.g. duplicate email).
HTTP/1.1 409 Conflict
{ "error": "Email already registered" }Syntactically valid but semantically incorrect. Use for validation errors.
HTTP/1.1 422 Unprocessable Entity
{ "errors": [{ "field": "age", "message": "Must be positive" }] }Rate limit exceeded.
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "error": "Rate limit exceeded" }Unexpected server error. Generic catch-all.
HTTP/1.1 500 Internal Server Error
{ "error": "Something went wrong" }Upstream server returned invalid response.
HTTP/1.1 502 Bad Gateway
# Often seen when a reverse proxy fails to reach app serverServer temporarily unavailable (overloaded or maintenance).
HTTP/1.1 503 Service Unavailable
Retry-After: 300Upstream server timed out.
HTTP/1.1 504 Gateway Timeout
# Reverse proxy did not receive a timely responseStandard status codes mapped to REST CRUD operations
GET /resources → 200 OK (list)
GET /resources/:id → 200 OK or 404 Not Found
POST /resources → 201 Created + Location header
PUT /resources/:id → 200 OK (return updated) or 204 No Content
PATCH /resources/:id → 200 OK (return updated) or 204 No Content
DELETE /resources/:id → 204 No Content or 404 Not Found
# Authentication errors
No token provided → 401 Unauthorized
Token invalid/expired → 401 Unauthorized
Valid token, no access → 403 ForbiddenConsistent error response format across your API
// Standard error shape
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" },
{ "field": "age", "message": "Must be a positive integer" }
]
}
}
// Simple error shape
{
"error": "Resource not found",
"statusCode": 404
}Which redirect code to use and when
Resource moved permanently?
→ Preserves GET method? → 301 Moved Permanently
→ Preserves any method? → 308 Permanent Redirect
Resource moved temporarily?
→ Preserves GET method? → 302 Found
→ Preserves any method? → 307 Temporary Redirect
After POST → redirect to result?
→ 303 See Other (redirect with GET)
Cached content still valid?
→ 304 Not ModifiedReturn 201 Created (not 200) when a new resource is created, and include the Location header
Use 204 No Content for successful DELETE or PATCH requests with no response body
Distinguish 401 (not authenticated) from 403 (authenticated but not authorized)
Use 422 for validation errors instead of 400 — it better communicates the problem
Always return a consistent error response shape so API consumers can handle errors uniformly