API reference / errors

Errors & statuses

Distinguish validation, authentication, availability and human-review outcomes.

Error envelope

{
  "error": {
    "code": "validation_failed",
    "message": "purpose is required",
    "request_id": "svr_01J...",
    "details": {"field": "purpose"}
  }
}

Handling rules

Condition	Retry?	Guidance
401 unauthorized	After fixing auth	Refresh or rotate token.
422 validation_failed	After fixing payload	Correct fields; no paid call expected.
503 provider_unavailable	Not with a new key	Keep the same key and inspect state.
202 manual_review	No	Escalate for human assessment.
Completed no match	No	Record according to policy; may be chargeable.

Client pattern

if response.status == 202:
    keep_request_id(response)
    show_manual_review()
    # do not create another idempotency key