Choosing the Right REST API Status Code

In a REST API, the status code is a contract that lets clients understand a response without reading your docs. A well-chosen code tells the client whether to retry, what to show the user, and whether it can cache. An API that returns 200 for everything and hides a success flag in the body forces clients to parse every response and throws away the benefits of HTTP infrastructure — caches, proxies, and monitoring.

Success: 200 / 201 / 204

200 OK: The general success case. Returning a resource on GET, or returning the updated representation after a PUT/PATCH.
201 Created: A new resource was created. Use it when a POST adds an item to a collection, and put the new resource's URL in the Location header.
204 No Content: Success with nothing to return. Ideal for a successful DELETE or a PUT where no body is needed.

POST /v1/users HTTP/1.1
Content-Type: application/json

{"email":"a@example.com"}

HTTP/1.1 201 Created
Location: /v1/users/u_92311
Content-Type: application/json

{"id":"u_92311","email":"a@example.com"}

Client errors: 400 / 401 / 403 / 404 / 409 / 422 / 429

400 Bad Request: The request is malformed — broken JSON, a missing required parameter.
401 Unauthorized: Missing or invalid credentials. Advertise the scheme with WWW-Authenticate.
403 Forbidden: Authenticated, but not allowed to perform this action.
404 Not Found: The target resource does not exist. Sometimes used instead of 403 to hide a resource's existence.
409 Conflict: A conflict with the current state — duplicate creation, an optimistic-lock version mismatch.
422 Unprocessable Entity: Syntactically valid but semantically invalid — bad email format, out-of-range value.
429 Too Many Requests: Rate limit exceeded. Use Retry-After to tell the client when to try again.

Distinguishing 400 from 422 trips up many teams. By convention, 400 means 'the server couldn't even parse the request' (broken body), while 422 means 'it parsed, but a field failed a validation rule.' Picking one convention and applying it consistently across the whole API matters more than any individual choice.

Server errors and retries: 500 / 503

500 Internal Server Error is the catch-all for an unexpected server-side exception. 503 Service Unavailable signals a temporary inability to handle the request — overload or maintenance — and can advertise a recovery time via Retry-After. The 5xx codes and 429 are the ones a client may safely retry with exponential backoff.

Retrying safely with idempotency keys

On a flaky network, creating a payment or order with POST can leave you in the 'request arrived but the response was lost' state. Blindly retrying risks a duplicate. The fix: the client sends a unique value in an Idempotency-Key header, and the server executes a given key only once, then replays the stored original response for any later request bearing the same key.

POST /v1/charges HTTP/1.1
Idempotency-Key: 3f9c1b7a-2e5d-4a11-9c8e-77b0a1d2e4f6
Content-Type: application/json

{"amount":5000,"currency":"krw"}

Consistency is the ultimate goal of status-code design. Use the same code for the same kind of situation every time, standardize your error body (for example an error object containing code and message fields), and document what each code means. That lets client developers write predictable, defensive handling.