API Reference

Errors

Typed error envelope, error types, and how to handle each.

Failures are signalled with both an HTTP status code and a typed JSON envelope. Always inspect error.type (the broad family) and error.code (the specific reason) — message is human-friendly and may change wording over time.

Error envelope

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "Field 'name' is required.",
    "param": "name",
    "request_id": "req_8f2a1b3c4d5e6f70"
  }
}

Error types

invalid_request — 4xx. Your input is malformed: missing fields, wrong types, schema validation failure.
authentication_error — 401. Token is missing, malformed, expired, revoked, or hits the wrong environment.
permission_error — 403. The token authenticated successfully but lacks the required scope or tries to access another organization.
not_found — 404. The resource does not exist or is not visible to your token.
rate_limit_error — 429. You exceeded a rate-limit bucket. Retry after the time given by the Retry-After header.
conflict — 409 / 422. The request collides with the current state — for example, an Idempotency-Key reused with a different body.
server_error — 5xx. Something broke on our side. Quote the request_id to support and retry with backoff.

Recommended handling

Treat any 5xx or network failure as transient and retry with exponential backoff capped at 30 seconds.
Never retry a 4xx without changing the request — you will keep getting the same error.
Log request_id for every failed call. Support tickets that include it are resolved measurably faster.