Error Codes - AgentCard

All API errors return a JSON body with an error code and a human-readable description. Some errors include additional context fields.

{
  "error": "insufficient_balance",
  "description": "The card does not have sufficient balance for this transaction."
}

Card Creation Errors

These errors may be returned when calling POST /cards.

Code	Status	Description
`invalid_amount`	400	The requested card amount is invalid or out of range.
`amount_exceeds_limit`	400	The requested amount exceeds the maximum allowed card limit.
`beta_capacity_reached`	403	The beta program has reached its current capacity.
`cardholder_not_found`	404	No cardholder record was found for this user.
`cardholder_incomplete`	400	The cardholder profile is missing required information.
`payment_method_required`	422	A valid payment method must be attached before creating a card.
`card_declined`	402	The payment method was declined by the issuer.
`payment_authorization_failed`	402	The payment authorization could not be completed.
`no_shortcut_cards_available`	503	No shortcut cards are currently available for provisioning.
`card_creation_failed`	500	An unexpected error occurred while creating the card.

These errors may be returned when recording a card transaction.

Code	Status	Description
`invalid_card_id`	400	The provided card ID is malformed or invalid.
`invalid_transaction_amount`	400	The transaction amount is invalid or out of range.
`invalid_merchant`	400	The specified merchant is invalid or not recognized.
`card_not_found`	404	No card was found with the given ID.
`not_shortcut_card`	400	The specified card is not a shortcut card.
`card_status_invalid`	409	The card is not in a valid status for this operation. Returns `currentStatus`.
`insufficient_balance`	400	The card does not have sufficient balance for this transaction.
`amount_exceeds_card_limit`	400	The transaction amount exceeds the card’s spending limit.
`pi_capture_failed`	402	The payment intent capture failed. Returns `reason`.
`pi_capture_timeout`	402	The payment intent capture timed out. Returns `reason`.
`payment_not_found`	404	No payment was found with the given ID.
`payment_not_refundable`	409	The payment is not in a refundable state.
`refund_failed`	402	The refund could not be processed.

Code	Status	Description
`internal_error`	500	An internal server error occurred.

All error responses follow this structure:

{
  "error": "error_code",
  "description": "Human-readable description of what went wrong."
}

Some errors include additional context fields:

409 (card_status_invalid)

{
  "error": "card_status_invalid",
  "description": "The card is not in a valid status for this operation.",
  "currentStatus": "CLOSED"
}

402 (pi_capture_failed)

{
  "error": "pi_capture_failed",
  "description": "The payment intent capture failed.",
  "reason": "card_declined"
}