Status codes are behavior contracts, not decoration. Clients automate around them.

Question

Which HTTP status codes should my API team standardize to keep client behavior predictable?

Quick answer

Use this baseline:

  1. 200/201 for successful resource operations,
  2. 400 for client request shape errors,
  3. 401/403 for auth and permission boundaries,
  4. 404 for missing resources,
  5. 409 for state conflicts,
  6. 429 for rate policy enforcement,
  7. 5xx only for server-side fault.

Contract checks

  1. Return the same code for the same failure class every time.
  2. Keep error payload schema stable across endpoints.
  3. Never hide server faults behind 200 with error text in body.

Predictable codes reduce client branching complexity fast.

Common failure pattern

Teams use 500 as a catch-all and lose observability into real error classes.

Baseline status mapping

ScenarioCode
Valid read/update succeeded200
Resource created201
Request shape invalid400
Missing/invalid auth401
Authenticated but forbidden403
Resource not found404
State conflict409
Rate policy hit429
Server fault5xx

Keep this mapping stable across services and your client complexity drops fast.

10-minute action step

  1. Pick one high-traffic endpoint and one failure mode.
  2. Define the exact API contract behavior you expect under load.
  3. Simulate burst traffic and verify status codes, headers, and retry guidance.
  4. Document one contract invariant and enforce it in automated tests.

Success signal

Your team can predict failure behavior from the contract without checking production logs.