The error envelope and status codes

Q: Is 422 different from 400?

Yes. 400 means the request was malformed (unparseable JSON, wrong content type). 422 means it parsed fine but a value failed a business rule — the param field points at the culprit.

2 min read

error.codeBranch on this

4 classesClient / auth / rate / server

Never HTMLAlways JSON

The envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "consent_required",
    "message": "fields.consent must equal \"yes\".",
    "param": "fields.consent"
  }
}

Field	Type	Notes
`type`	string	Broad class: `invalid_request_error`, `authentication_error`, `rate_limit_error`, `api_error`.
`code`	string	Specific, stable machine code. This is what you branch on.
`message`	string	Human-readable. Safe to log; do not parse.
`param`	string?	The offending field, when the error is about one input.

Status → class

Status	type	Meaning	Retry?
`400`	invalid_request_error	Malformed request (bad JSON, wrong shape)	No — fix the request
`401`	authentication_error	Missing/invalid credential (partner plane)	No — fix auth
`403`	authentication_error	Authenticated but not permitted	No
`404`	invalid_request_error	Resource or route not found	No
`409`	invalid_request_error	Conflict (e.g. idempotency key reuse)	No
`422`	invalid_request_error	Well-formed but failed validation	No — fix the field
`429`	rate_limit_error	Rate limit exceeded	Yes — after `Retry-After`
`500`	api_error	Unexpected server error	Yes — with backoff
`503`	api_error	Temporarily unavailable	Yes — with backoff

How to handle

Split errors into three buckets. Fix-the-request (400/404/409/422): never retry blindly — the same request will fail again. Fix-the-auth (401/403): re-check the credential. Retry-able (429/5xx): back off and retry, honouring Retry-After on a 429. Full per-code detail is in the error code catalogue.

Frequently asked questions

Should I branch on the HTTP status or the error code?

Both. Use the status for the broad retry/no-retry decision, and the code for the specific user-facing behaviour. The code is stable; the message wording may be refined over time.

Can an error ever come back as HTML?

API errors are always the JSON envelope. If you ever receive HTML, you have hit an edge/proxy layer (e.g. a WAF or a 502 from infrastructure) rather than the API itself — treat it as a retry-able server error.

Is 422 different from 400?

Yes. 400 means the request was malformed (unparseable JSON, wrong content type). 422 means it parsed fine but a value failed a business rule — the param field points at the culprit.