Errors

HTTP status codes

Status	Meaning
`200`–`299`	Successful request.
`400`	Missing, invalid, or conflicting parameters.
`401`	Missing or invalid credential.
`403`	Credential lacks permission or a publishable key attempted a protected operation.
`404`	Resource was not found within the authenticated organization.
`409`	Idempotency key or resource-state conflict.
`422`	Request is syntactically valid but violates a product rule.
`429`	Request was rate limited.
`503`	Temporary dependency, lock, or service failure.

Endpoints return a short error description and may include a stable code or additional fields:

{
  "error": "insufficient credits",
  "code": "insufficient_credits"
}

Do not parse human-readable text when a machine-readable code is available.

Retry read requests only within your latency and request budget.
Retry idempotent mutations with the same idempotency key and payload.
Retry events with the same transaction ID.
Honor Retry-After when returned.
Do not retry validation, authorization, or insufficient-credit decisions without changing the underlying state.

Error	Check
Invalid API key	Key prefix, revocation state, and target environment.
Customer not found	Server-owned external customer mapping and organization scope.
Feature not found	Feature code and plan entitlement configuration.
Subscription not active	Checkout payment state and subscription boundary.
Insufficient credits	Effective balance, source expiry, Entity status, and pool policy.