Choosing HTTP status codes clients will not misread
Status codes are part of your contract. Partners often code against them before they read your JSON schema.
Separate “fix the request” from “we failed”
Use 4xx when the caller can change something: missing header, invalid date range, unknown SKU. Use 5xx when your service or a dependency failed and retry might help. Mixing these confuses batch jobs that retry every 5xx blindly.
Be careful with 401 and 403
Many mobile templates log users out on any 401. If your token expired, say so in a machine-readable error_code and document that 401 always means re-authentication. Reserve 403 for authorised users who lack scope on that resource.
Validation belongs in 422 or 400—pick one
We standardise on 422 for semantic validation (business rules) and 400 for malformed JSON or impossible enums. Document the rule once in your OpenAPI description and never swap mid-version.
409 for state conflicts
When a shipment is already dispatched, return 409 with the current state in the body so integrators do not parse error text. This saves support calls.
Document a status matrix
Add a table to your partner guide listing each endpoint’s possible statuses. It takes an hour and prevents weeks of Slack debate.
Ask us to review your error model before partner onboarding.