Errors - Chief API

Every error from the Chief Public API uses the same JSON envelope:

{
  "code": "publicapi.auth.invalid",
  "humane": "The provided API key is invalid or has been revoked.",
  "statusCode": 401
}

Field	Description
`code`	Stable, dotted, lowercase identifier (`domain.operation.reason`). Use for i18n keys and analytics.
`humane`	Plain English safe to show end users.
`statusCode`	Mirrors the HTTP status code.

code values are additive. Existing codes are never reworded.

HTTP status reference

Status	Meaning
`400`	Malformed request, validation failure, or missing tenancy header.
`401`	Authentication failure.
`404`	Resource does not exist or is outside the caller’s reach.
`500`	Unexpected server error.

Code	HTTP	When
`publicapi.auth.invalid`	401	PAT is missing, malformed, or revoked.
`publicapi.tenancy.project.missing`	400	`X-Project-Id` is missing or malformed.

Additional operation-specific codes may appear in v1. Prefer HTTP status for broad handling and code when you need precise branching.

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

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).

Situation	Typical response
Both `after_id` and `before_id` set	HTTP `400`
`limit` outside 1–100	HTTP `400`

See Pagination for valid query parameters.