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 or API access is not approved	Complete individual or corporate 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.

Verification and card-account errors

Code	Action
`MONTHLY_CARD_LIMIT_REACHED`	Individual issuance is limited to 500 per UTC calendar month; pending requests count.
`WHOLE_USD_REQUIRED`	Request a whole USD invoice amount, at least 10 USD.
`BELOW_PROVIDER_MINIMUM`	Use the current `minimum` returned in the error response.
`FUNDING_INVOICE_PENDING`	Retrieve the existing invoice before creating another.
`INVOICE_RESULT_UNKNOWN`	Do not retry creation or pay a new invoice. Contact support for reconciliation.
`USE_CARD_ACCOUNT_INVOICE`	Replace the retired funding-address endpoint with card-account invoices.
`STATEMENT_RANGE_TOO_LARGE`	Shorten the date range; a statement can contain up to 10,000 ledger entries.

Get started

Cards

Integration

Reliability

Read both HTTP status and the error body

Transport errors

Verification and card-account errors

​Read both HTTP status and the error body

​Transport errors

​Verification and card-account errors

Read both HTTP status and the error body

Transport errors

Verification and card-account errors