REST status codes

Status codes communicate outcome class to clients, proxies, and retry logic. Use the smallest accurate code; put details in the body.

| Code | When to use | |------|-------------| | 200 OK | Successful GET, PUT, PATCH with body | | 201 Created | POST created resource; include Location | | 204 No Content | Successful DELETE or update with no body | | 400 Bad Request | Malformed syntax, unknown fields, invalid JSON | | 401 Unauthorized | Missing or invalid authentication | | 403 Forbidden | Authenticated but not allowed | | 404 Not Found | Resource absent or hidden (policy choice) | | 409 Conflict | State conflict (duplicate, version mismatch) | | 422 Unprocessable Entity | Valid JSON but business validation failed | | 429 Too Many Requests | Rate limit; send Retry-After | | 500 Internal Server Error | Unexpected server fault | | 503 Service Unavailable | Overload or dependency down; Retry-After |

					HTTP/1.1 201 Created
Location: /orders/7f3a2c
Content-Type: application/json

{"id":"7f3a2c","status":"pending"}
				

					HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{"type":"order/already-shipped","title":"Cannot cancel shipped order"}
				

On interviews: distinguish 401 vs 403, 400 vs 422, when 404 hides existence, and why 500 must not leak stack traces.

Common pitfalls: 200 with error payloads, 404 for auth failures inconsistently, 500 for validation errors, and omitting Retry-After on 429/503.

The trade-off is fine-grained codes versus client simplicity — document a stable error catalog either way.

Checklist:

• Match code to retryability (4xx usually not, 5xx/429 maybe).
• 201 + Location on create.
• Consistent 401/403 semantics.
• Problem details in body, not status alone.