Error Codes
When the API returns an error, the response body includes a JSON object with code, type, and message fields.
{
"code": "card_declined",
"type": "card_error",
"message": "Your card was declined."
}For card_declined, a decline_code field is also present with the issuer's reason.
Error Types
| Type | Description |
|---|---|
api_error | An internal error occurred on our side. Retry the request. |
authentication_error | Authentication with the API failed. Check your API key or JWS signature. |
invalid_request_error | The request has invalid parameters or is missing required fields. |
card_error | The card was declined or failed validation. |
rate_limit_error | Too many requests. Back off and retry. |
idempotency_error | The idempotency key was used with different request parameters. |
HTTP Status Codes
| Status | Meaning |
|---|---|
200 | Success. |
400 | Bad Request. Invalid parameters or missing required fields. |
401 | Unauthorized. Invalid or missing authentication credentials. |
403 | Forbidden. The request is not allowed. |
404 | Not Found. The requested resource does not exist. |
409 | Conflict. The resource is in a state that conflicts with the request. |
429 | Too Many Requests. Rate limit exceeded. |
500 | Internal Server Error. Something went wrong on our side. |
Payment Errors
amount_too_large
The charge amount exceeds the maximum allowed limit.
amount_too_small
The charge amount is below the minimum allowed limit.
authentication_required
The payment requires additional customer authentication (e.g. 3D Secure).
balance_insufficient
The account has insufficient funds for the requested transfer or payout.
Card Errors
card_declined
The card has been declined. Check the decline_code field for the specific reason.
Common decline codes:
| Decline Code | Description |
|---|---|
insufficient_funds | The card has insufficient funds to complete the payment. |
lost_card | The card has been reported lost. |
stolen_card | The card has been reported stolen. |
generic_decline | The card was declined for an unspecified reason. |
do_not_honor | The issuing bank has declined the transaction. |
transaction_not_allowed | The card does not support this type of transaction. |
expired_card
The card has expired. Ask the customer to use a different card.
incorrect_cvc
The card's security code (CVC/CVV) is incorrect.
incorrect_number
The card number is incorrect.
invalid_cvc
The card's security code is invalid (wrong format or length).
invalid_expiry_month
The card's expiration month is incorrect.
invalid_expiry_year
The card's expiration year is incorrect.
invalid_number
The card number is not a valid credit card number.
processing_error
An error occurred while processing the card. Retry the payment.
Payment Intent Errors
payment_intent_unexpected_state
The payment intent is in a state that does not allow the requested operation. For example, trying to confirm a payment intent that has already succeeded.
payment_intent_authentication_failure
The payment method failed authentication (e.g. 3D Secure challenge failed).
payment_intent_invalid_parameter
One or more parameters provided for the payment intent are invalid.
payment_intent_payment_attempt_expired
The latest payment attempt has expired. Create a new payment intent or retry.
payment_intent_payment_attempt_failed
The latest payment attempt failed. Check last_payment_error for details.
Payment Method Errors
payment_method_not_available
The payment method processor is temporarily unavailable. Retry later.
payment_method_currency_mismatch
The currency does not match the payment method's supported currencies.
payment_method_unactivated
The payment method has not been activated. Contact support.
payment_method_provider_decline
The payment or setup was declined by the issuer or provider.
payment_method_provider_timeout
The payment method failed due to a timeout with the provider.
3D Secure Errors
three_d_secure_authentication_failed
The 3D Secure authentication challenge was not completed successfully.
three_d_secure_not_supported
The card or issuer does not support 3D Secure authentication.
three_d_secure_action_expired
The 3D Secure authentication action has expired. Retry the payment.
three_d_secure_invalid_cryptogram
The 3D Secure cryptogram provided is invalid or has already been used.
Refund Errors
charge_already_refunded
The charge has already been fully refunded.
charge_disputed
The charge is under dispute and cannot be refunded. Wait for the dispute to be resolved.
refund_amount_exceeds_charge
The refund amount exceeds the original charge amount minus previous refunds.
Request Errors
parameter_missing
One or more required parameters are missing from the request.
parameter_invalid_empty
A required parameter was provided but is empty.
parameter_unknown
The request contains one or more unexpected parameters.
parameters_exclusive
Two or more mutually exclusive parameters were provided together. For example, both payment_method_id and confirmation_token in a confirm request.
resource_missing
The requested resource does not exist. Verify the ID is correct.
idempotency_key_in_use
The idempotency key is currently being used by another in-flight request.
Authentication Errors
api_key_expired
The API key has expired. Generate a new key.
api_key_invalid
The API key provided is invalid or malformed.
jws_signature_invalid
The JWS signature verification failed. Check your signing key and algorithm.
jws_token_expired
The JWS token has expired. Generate a new signed request.
Rate Limiting
rate_limit
Too many requests in a short period. Implement exponential backoff and retry.
Rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
X-RateLimit-Reset | Unix timestamp when the rate limit resets. |