Errors

Most errors are returned as JSON with this base shape:

{ "error": "Human-readable message" }

The exact field set varies by error type — every body has an error string, and some bodies attach extra fields (issues, policy, liveQuoteAvailable) as documented below. Treat the error string as human-facing; key your retry/handling logic off the HTTP status and the extra fields.

Validation errors include issues:

{
  "error": "validation_failed",
  "issues": [
    { "path": ["currency"], "message": "Required", "code": "invalid_type" }
  ]
}

Policy-blocked operations include the offending policy:

{
  "error": "Order exceeds maximum unapproved amount",
  "policy": { "name": "Max order amount", "type": "order_create" }
}

Status codes

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created
204 No Content	Request succeeded, nothing to return (used by DELETE)
400 Bad Request	Validation failed; body malformed; required parameter missing
401 Unauthorized	API key missing, unknown, or revoked
403 Forbidden	Authenticated but the key lacks required scope, or a policy blocked the operation
404 Not Found	Resource does not exist for the calling tenant
409 Conflict	Terminal-state conflict (e.g. completing an already-completed payment)
429 Too Many Requests	Rate limit exceeded; see Rate limits
500 Internal Server Error	Bug on our side — safe to retry idempotent requests
502 Bad Gateway	Downstream billing system returned an error or could not be reached

Common error codes

error value	When it appears
validation_failed	Request body failed Zod validation
Insufficient scope. …	API key lacks required scope
Account not found	Account ID does not match a tenant-owned account or billing-system account
Subscription not found	Subscription ID does not exist for this tenant
No active billing integration configured	Endpoint needs Stripe/Zuora but none is active
Live billing-system quote failed: …	Order contains non-modeled charges and the live quote roundtrip failed
Rate limit exceeded. Try again later.	You exceeded your key's rate limit

Retrying

• 4xx errors should not be retried without changing the request.

• 429 should be retried after X-RateLimit-Reset (a Unix timestamp).

• 5xx errors are safe to retry; use exponential backoff. Be aware that the API does not currently de-duplicate retried writes server-side, so guard against duplicates client-side (e.g. don't retry a POST that may have succeeded without first checking via GET).

Related

• Rate limits