Errors and retries

Read both HTTP status and the error body

Errors may use { "statusCode": 403, "message": "SCOPE_REQUIRED" } or a validation body with a code and explanatory message. Preserve the operation ID and your idempotency key in your logs; never log credentials or card details.

Code	Meaning	Next action
`INVALID_KEY`	Key is missing, invalid, or revoked	Check credentials and environment
`SCOPE_REQUIRED`	Key lacks a required permission	Issue an appropriately scoped key
`VERIFICATION_REQUIRED`	Live access is not approved	Complete company verification
`LIVE_INTEGRATION_NOT_ENABLED`	Live capability is unavailable	Contact support; do not retry purchases
`VALIDATION_ERROR`	Request fields are invalid	Correct the request
`PRODUCT_NOT_FOUND`	Product is unavailable in this environment	Refresh the catalog
`BELOW_MINIMUM` / `ABOVE_MAXIMUM`	Amount is outside product limits	Use the published product limits
`VERIFIED_HOLDER_REQUIRED`	Holder is not eligible for issuance	Resolve holder verification
`INSUFFICIENT_BALANCE`	Available balance is too low	Fund the company account
`QUOTE_CHANGED`	Expected total differs from the current quote	Re-quote and confirm the new price
`IDEMPOTENCY_CONFLICT`	Key was reused with different data	Retrieve the original operation
`INVALID_CURSOR`	Pagination cursor is invalid	Use the returned cursor unchanged
`RATE_LIMITED`	Request budget exceeded	Back off with jitter

Transport errors

After a timeout or connection failure on POST /operations, retry the exact request using the original idempotency key. Do not create a new order identifier to escape an error. Use bounded exponential backoff with jitter for transient read errors. Stop on a persistent 4xx error and correct the cause. An operation in manual_review retains an unresolved outcome and may retain its reserve; contact support with the operation ID.

Get started

Cards

Integration

Reliability

Read both HTTP status and the error body

Transport errors

​Read both HTTP status and the error body

​Transport errors

Read both HTTP status and the error body

Transport errors