Error codes
Error codes provide stable, programmatic identifiers for specific failure conditions.
Use these codes to implement conditional logic in your integration.
Structure
Error codes are returned in the code field of the error object.
Example
{
"type": "card_error",
"code": "card_declined",
"decline_code": "insufficient_funds",
"message": "Your card has insufficient funds.",
"trace_id": "trc_123"
}
Categories
Invalid request errors
Errors caused by invalid input or request structure.
Examples:
parameter_invalidmissing_required_paramamount_too_large
Recommended handling:
- Do not retry
- Fix the request data
- Display validation errors to the user
Authentication errors
Errors caused by missing or invalid credentials.
Examples:
authentication_failedinvalid_api_key
Recommended handling:
- Verify credentials
- Do not retry without fixing authentication
Card errors
Errors caused by card or issuer behavior.
Examples:
card_declinedexpired_cardincorrect_number
Recommended handling:
- Use
decline_codeandadvice_code - Prompt the customer for action if needed
Processing errors
Errors caused by temporary processing issues.
Examples:
processing_errorissuer_unavailable
Recommended handling:
- Retry later
- Do not retry immediately in a tight loop
Rate limiting errors
Errors caused by exceeding request limits.
Examples:
rate_limit_exceeded
Recommended handling:
- Back off and retry later
- Implement exponential backoff
Handling strategy
Determine whether the error is caused by input, authentication, or processing.
Use the code to identify the specific failure condition.
Decide whether to retry, prompt the user, or fail the request.
Best practices
- Treat error codes as stable integration contracts
- Avoid parsing error messages programmatically
- Combine
codewith other fields such asdecline_code - Keep retry logic explicit and controlled
