Errors

The API uses conventional HTTP status codes and returns one typed error shape.

Error shape

Every error body has type, code, and message, plus a nullable request_id. Branch on code; quote request_id to support.

application/json

{
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "limit must be between 1 and 100.",
  "request_id": "req_9F2xa7Qh"
}

HTTP status codes

Status	Meaning
`200` / `201`	Success.
`400`	Malformed request.
`401`	Missing or invalid key.
`402`	Payment or entitlement required.
`403`	Authenticated but missing a required scope or entitlement.
`404`	Resource does not exist, or the feature is not enabled for your org.
`409`	Conflict (for example, idempotency-key reuse with a different body).
`422`	Validation failed.
`429`	Rate limited — see Rate limits.
`5xx`	Server error. Retry idempotent calls with backoff.

Request IDs

Every response carries a server-generated X-Request-Id. You may send your own X-Request-Id as a correlation hint, but the server always issues its own for the record.