CARDS

Errors

Common error code values returned across all Virtual Cards endpoints.

Use this page to

Look up what a code in an error response means
Decide how to handle each error type in your integration
Understand when a debit is auto-refunded vs. when you need to act

Code	Meaning
`INVALID_REQUEST`	Missing/invalid fields, e.g. non-positive `amount`
`UNAUTHORIZED`	Business not found or inactive
`NOT_FOUND`	Customer or card not found
`KYC_REQUIRED`	The customer lacks an approved government ID and/or proof of address
`KYC_INCOMPLETE`	The approved government ID is missing its document number
`INSUFFICIENT_FUNDS`	Business USD wallet balance too low
`CARD_NOT_READY`	The card is still provisioning, no `card_id` yet
`CARD_NOT_ACTIVE`	Operation requires an `active` card, e.g. funding a frozen card
`CARD_TERMINATED`	The card has been permanently closed
`INVALID_STATE`	e.g. freezing an already-frozen card
`REQUEST_FAILED`	The card partner rejected the operation, any debit auto-refunded
`SERVICE_UNAVAILABLE`	Card issuing temporarily unavailable

Error shape

{
  "status": "error",
  "code": "CARD_NOT_ACTIVE",
  "message": "This operation requires the card to be active."
}

Handling recommendations

Situation	Recommended handling
`INVALID_REQUEST`	Fix the request payload, check `amount` is positive and within any card balance limits
`UNAUTHORIZED`	Check your access token and business status
`NOT_FOUND`	Confirm the `customer_id` / `tracking_id` you're using is correct
`KYC_REQUIRED`	Submit the missing document via the Customer Enrollment & KYC section, then check status before retrying
`KYC_INCOMPLETE`	Resubmit the government ID with its document number included
`INSUFFICIENT_FUNDS`	Top up the business USD wallet before retrying
`CARD_NOT_READY`	Wait for the Card Issuance Status Update webhook, or poll Get Card
`CARD_NOT_ACTIVE`	Unfreeze the card first, or check its current status via Get Card
`CARD_TERMINATED`	This card can no longer be used. Issue a new one if needed
`INVALID_STATE`	Check the card's current status before retrying the same action
`REQUEST_FAILED`	Any debit that has already been auto-refunded is safe to retry, or should be investigated with the customer
`SERVICE_UNAVAILABLE`	Transient, retry after a short delay

Note: Every wallet debit (issuance, funding) is auto-reversed on a definitive partner rejection - synchronously when the call fails, or via the card-failed webhook if the card is declined after being queued.

Questions? Email [email protected]. Also on GitBook.