Skip to main content
Every error from the Chief Public API uses the same JSON envelope:
code values are additive. Existing codes are never reworded.

​
HTTP status reference

​
Documented error codes

A 401 usually means the token was revoked or has passed its expiry. Both are visible in the Chief app — see Managing API tokens securely.
Additional operation-specific codes may appear in v1. Prefer HTTP status for broad handling and code when you need precise branching.

​
Validation errors

Invalid JSON bodies, unknown fields, or id shape mismatches typically return HTTP 400. Resource ids use fixed prefixes and lengths:

​
Client recommendations

  • Log code and HTTP status for support and metrics.
  • Show humane to users when appropriate; do not parse it for control flow.
  • Retry 5xx with exponential backoff.
  • Do not retry 4xx unless you fix the request (for example, add a valid X-Project-Id).

​
Pagination errors

See Pagination for valid query parameters.

​
FAQ

Use the HTTP status for broad handling and code when you need precise branching. Do not parse humane for control flow — it is display copy.
Retry 5xx with exponential backoff. Do not retry 4xx unless you have fixed the request, for example by adding a valid X-Project-Id.
No. code values are additive and existing codes are never reworded, so they are safe as i18n keys and analytics dimensions.
Check the id shapes first. Resource ids use fixed prefixes and lengths, and a mismatch returns 400. Sending both after_id and before_id, or a limit outside 1–100, also returns 400.