Status Codes

The first digit sets the class, so even a client that does not know a specific code can react correctly. 1xx is informational, an interim response such as 100 Continue or 103 Early Hints before the final one. 2xx means success: use the response. 3xx means redirection or use a cached copy: follow Location or reuse what you have, as with 304. 4xx means the client made a mistake, so fix the request instead of retrying it unchanged, apart from 408 and 429 after waiting. 5xx means the server failed, so idempotent requests may be retried with backoff and operators should be alerted.

Return 201 Created with a Location header holding the URI of the new resource, for example /api/orders/5001. Most APIs also return a representation of the created resource in the body, so the client gets generated fields such as the id, timestamps and status without a second GET; adding an ETag lets the client start conditional updates straight away. In Spring, ResponseEntity.created(uri).body(view) does all of this, and ServletUriComponentsBuilder can build the URI from the current request. Use 200 only when the POST did not create a resource, and 202 when creation will happen asynchronously. Combine creation with an idempotency key so retries do not create duplicates.

401 Unauthorized actually means unauthenticated: the request has no valid credentials, for example a missing, expired or badly signed token, and the response must include a WWW-Authenticate header such as Bearer error="invalid_token" telling the client how to authenticate. Retrying after logging in or refreshing the token can succeed. 403 Forbidden means the server knows who the caller is but that identity is not allowed to do this, for example a token without the orders:write scope; re-authenticating will not help. For resources belonging to another tenant, many APIs return 404 instead of 403 so they do not reveal that the resource exists. Spring Security produces 401 and 403 through separate handlers.

Return 202 Accepted when the server has validated and queued the request but the actual work will finish later, such as report generation, bulk imports, video processing or a payment awaiting a slow provider. The response should not pretend the work is done. Include a Location header pointing to a status resource like /api/report-jobs/77, optionally a Retry-After hint, and a body with the job id and state. The client polls that resource, which returns RUNNING with progress and then DONE with a link to the result, or redirects with 303. This keeps HTTP connections short, avoids gateway 504 timeouts and fits naturally with queue-based processing behind the API.

409 Conflict means the request conflicts with the current state of the resource according to business rules, regardless of what the client sent as preconditions: cancelling an order that has already shipped, or creating a username that is taken. 412 Precondition Failed is narrower: the client sent a conditional header such as If-Match with an ETag, and the current version no longer matches, which is optimistic concurrency at the HTTP level. A 412 tells the client to reload the resource, merge and retry; a 409 tells it the operation is not allowed in this state. If you require preconditions on updates, return 428 when the client omits them.

Because everything outside your application code reads the status line, not your JSON. With 200 for errors, CDNs and gateways cache failures as if they were valid content, retry libraries never retry real outages, circuit breakers never open, and SLO dashboards report 100 percent success during an incident. Client SDKs cannot throw typed exceptions, so every caller must parse a custom error flag and some will forget, silently treating failures as success. Browser and HTTP tooling behaviour breaks too. Use proper 4xx and 5xx codes with an RFC 9457 Problem Details body for the detail. Migrating a legacy always-200 API needs a transition period and updated client SDKs.

Status codes are the input to retry classification. Most 4xx responses, such as 400, 403, 404, 409 and 422, mean the request itself is wrong and will fail again, so never retry them unchanged; 401 can succeed only after re-authenticating. 408, 429 and 503 mean try later, so wait for Retry-After before retrying. 500, 502 and 504 and connection errors may be transient, so retry idempotent requests with exponential backoff and jitter and a small attempt limit. Non-idempotent POSTs that time out have an unknown outcome and need idempotency keys before retrying. Encode this once in Resilience4j or the client SDK so every team behaves the same.

Standardise by making the right thing the default and the wrong thing visible. Publish an organisation-wide status catalogue in the API guidelines that maps common situations, validation, not found, conflict, stale ETag, rate limit, to specific codes with RFC 9457 Problem Details bodies. Ship it as a shared Spring Boot starter with a @RestControllerAdvice and exception types so services map errors identically. Lint OpenAPI specs in CI with Spectral rules, for example requiring 201 plus Location on creation and documented 4xx responses. Back it with contract tests and dashboards by status class per API, and align gateway behaviour, timeouts and SDK retry policies with the same catalogue.