Error Codes

This document lists all payment error codes returned by the Axra Business Payments API. These codes appear in charge and refund responses when a payment fails.

Error Response Format

When a charge or refund fails, the response includes an error object:

{
  "paymentId": "bpay_01H...",
  "status": "failed",
  "amount": 49.99,
  "currency": "usd",
  "transactionId": "",
  "error": {
    "code": "card_declined",
    "message": "The card was declined by the issuing bank.",
    "isRetryable": false
  }
}

Field	Type	Description
`code`	string	Normalized Axra error code (see table below)
`message`	string	Human-readable error message
`isRetryable`	boolean	Whether the operation can be retried with the same inputs

Payment Error Codes

Card Errors

Code	Description	Retryable	Suggested Action
`card_declined`	The card was declined by the issuing bank	No	Ask customer to use a different card or contact their bank
`insufficient_funds`	The card has insufficient funds to complete the transaction	No	Ask customer to use a different card or add funds
`invalid_card`	The card number is invalid or does not match any known card type	No	Ask customer to re-enter card details
`expired_card`	The card has expired	No	Ask customer to use a non-expired card
`invalid_cvv`	The CVV/CVC code is incorrect	No	Ask customer to re-enter the CVV
`lost_stolen_card`	The card has been reported lost or stolen	No	Ask customer to use a different card

Authentication Errors

Code	Description	Retryable	Suggested Action
`authentication_required`	The transaction requires 3D Secure authentication	No	Redirect customer to the 3DS challenge URL

Processing Errors

Code	Description	Retryable	Suggested Action
`processing_error`	A generic processing error occurred	Yes	Retry after a brief delay
`rate_limit`	Too many requests in a short period	Yes	Wait and retry with exponential backoff
`provider_unavailable`	The payment processor is temporarily unreachable	Yes	Retry later

Validation Errors

Code	Description	Retryable	Suggested Action
`invalid_amount`	The charge amount is invalid (e.g., negative, zero, too large)	No	Correct the amount and retry
`invalid_currency`	The currency code is not supported	No	Use a supported currency code (ISO 4217)

Transaction Errors

Code	Description	Retryable	Suggested Action
`duplicate_transaction`	A transaction with these parameters was already processed	No	The original payment was likely successful. Check existing payments before retrying
`refund_exceeds_amount`	The refund amount exceeds the original charge amount	No	Reduce the refund amount
`transaction_not_found`	The referenced transaction was not found	No	Verify the transaction ID is correct

Configuration Errors

Code	Description	Retryable	Suggested Action
`configuration_error`	Merchant payment configuration is missing or invalid	No	Verify payment settings in the Axra dashboard

Catch-All

Code	Description	Retryable	Suggested Action
`unknown`	An unexpected error occurred	No	Contact Axra support with the payment details

HTTP Error Codes

In addition to payment-specific errors, the API returns standard HTTP error codes:

400 Bad Request

Returned when the request is malformed or contains invalid data.

{
  "statusCode": 400,
  "message": "Cannot refund a payment with status \"PENDING\"",
  "error": "Bad Request"
}

Common causes:

Missing required fields (amount, currency, card)
Invalid field values (negative amount, expired card date)
Invalid state transition (refunding a non-completed payment)
Checkout session expired or already completed
S2S charging not enabled for your business
Payment older than 180-day refund window
Too many payment attempts on a checkout session (rate limited to 5 per 15 minutes)

401 Unauthorized

Returned when authentication fails.

{
  "statusCode": 401,
  "message": "Invalid API key or secret",
  "error": "Unauthorized"
}

Common causes:

Invalid or missing x-api-key header
Expired JWT token
Invalid API key / secret combination
Business profile deactivated

404 Not Found

Returned when the requested resource does not exist.

{
  "statusCode": 404,
  "message": "Payment not found",
  "error": "Not Found"
}

Common causes:

Invalid payment ID
Payment belongs to a different business
Checkout session does not exist

409 Conflict

Returned when the operation conflicts with existing state.

{
  "statusCode": 409,
  "message": "Business profile already exists for this user",
  "error": "Conflict"
}

Common causes:

Attempting to create a duplicate business profile

Disputes are not errors per se, but they have financial consequences:

Event	Merchant Impact
`payment.disputed`	Full charge amount debited + dispute fee
`payment.dispute_won`	Full charge amount re-credited (dispute fee NOT refunded)
`payment.dispute_lost`	No further changes (charge + fee already debited)

Dispute fees are non-refundable regardless of outcome. The best defense against disputes is:

Use 3DS authentication (shifts fraud liability to issuer)
Provide clear billing descriptors
Respond to disputes promptly with evidence
Maintain records of customer transactions and communication

Debugging Tips

Look at isRetryable: Only retry when this is true. Retrying non-retryable errors wastes quota and may trigger rate limits.
Use test cards: Test card numbers trigger specific error scenarios. See the API Reference for the full list.
Review webhook delivery logs: Failed webhook deliveries are logged and visible in the Axra dashboard.
Contact support: For unknown errors or persistent configuration_error, contact Axra support with the paymentId and transactionId.

​Error Response Format

​Payment Error Codes

​Card Errors

​Authentication Errors

​Processing Errors

​Validation Errors

​Transaction Errors

​Configuration Errors

​Catch-All

​HTTP Error Codes

​400 Bad Request

​401 Unauthorized

​404 Not Found

​409 Conflict

​Dispute-Related Errors

​Debugging Tips

Error Response Format

Payment Error Codes

Card Errors

Authentication Errors

Processing Errors

Validation Errors

Transaction Errors

Configuration Errors

Catch-All

HTTP Error Codes

400 Bad Request

401 Unauthorized

404 Not Found

409 Conflict

Dispute-Related Errors

Debugging Tips