Errors

Error Envelope

All errors use the same envelope shape:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_field",
    "message": "The 'status' field must be one of: open, in_progress, completed.",
    "details": [
      { "field": "status", "message": "Invalid value." }
    ]
  },
  "meta": { "requestId": "req_01j..." }
}

Field	Type	Description
`error.type`	string	Machine-readable error category (see table below)
`error.code`	string	Specific error code within the category
`error.message`	string	Human-readable description
`error.details`	array, optional	Field-level details for validation errors
`meta.requestId`	string	Unique ID for the request — include this when contacting support

Error Types

Type	Status	Retry?	Notes
`validation_error`	400	No	Fix the request. Check `error.details` for field-level messages.
`authentication_error`	401	No	Key missing, revoked, or invalid. Check your `Authorization` header.
`authorization_error`	403	No	Key is valid but lacks the required scope. Create a key with the needed scopes.
`not_found_error`	404	No	Resource does not exist or is not accessible to your organization.
`conflict_error`	409	No	State conflict — for example, an in-flight duplicate idempotent request. Check the specific `error.code`.
`business_rule_error`	422	No	The request is structurally valid but violates a business rule. Check `error.message` for details.
`rate_limit_error`	429	Yes	Slow down. Wait for the duration in the `Retry-After` header before retrying.
`internal_error`	500	Yes	Server error. Retry with exponential backoff. If the error persists, contact support with `meta.requestId`.

Retrying Requests

429 rate_limit_error: Honor the Retry-After header (seconds). See Rate Limits for details.
500 internal_error: Retry with exponential backoff (start at 1s, double each attempt, cap at 60s). Idempotent GET requests can be retried unconditionally. For POST requests, use the Idempotency-Key header to avoid duplicate side effects — see Idempotency.
All other errors: Do not retry without changing the request.