Skip to main content
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
  }
}
FieldTypeDescription
codestringNormalized Axra error code (see table below)
messagestringHuman-readable error message
isRetryablebooleanWhether the operation can be retried with the same inputs

​
Payment Error Codes

​
Card Errors

CodeDescriptionRetryableSuggested Action
card_declinedThe card was declined by the issuing bankNoAsk customer to use a different card or contact their bank
insufficient_fundsThe card has insufficient funds to complete the transactionNoAsk customer to use a different card or add funds
invalid_cardThe card number is invalid or does not match any known card typeNoAsk customer to re-enter card details
expired_cardThe card has expiredNoAsk customer to use a non-expired card
invalid_cvvThe CVV/CVC code is incorrectNoAsk customer to re-enter the CVV
lost_stolen_cardThe card has been reported lost or stolenNoAsk customer to use a different card

​
Authentication Errors

CodeDescriptionRetryableSuggested Action
authentication_requiredThe transaction requires 3D Secure authenticationNoRedirect customer to the 3DS challenge URL

​
Processing Errors

CodeDescriptionRetryableSuggested Action
processing_errorA generic processing error occurredYesRetry after a brief delay
rate_limitToo many requests in a short periodYesWait and retry with exponential backoff
provider_unavailableThe payment processor is temporarily unreachableYesRetry later

​
Validation Errors

CodeDescriptionRetryableSuggested Action
invalid_amountThe charge amount is invalid (e.g., negative, zero, too large)NoCorrect the amount and retry
invalid_currencyThe currency code is not supportedNoUse a supported currency code (ISO 4217)

​
Transaction Errors

CodeDescriptionRetryableSuggested Action
duplicate_transactionA transaction with these parameters was already processedNoThe original payment was likely successful. Check existing payments before retrying
refund_exceeds_amountThe refund amount exceeds the original charge amountNoReduce the refund amount
transaction_not_foundThe referenced transaction was not foundNoVerify the transaction ID is correct

​
Configuration Errors

CodeDescriptionRetryableSuggested Action
configuration_errorMerchant payment configuration is missing or invalidNoVerify payment settings in the Axra dashboard

​
Catch-All

CodeDescriptionRetryableSuggested Action
unknownAn unexpected error occurredNoContact 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:
EventMerchant Impact
payment.disputedFull charge amount debited + dispute fee
payment.dispute_wonFull charge amount re-credited (dispute fee NOT refunded)
payment.dispute_lostNo further changes (charge + fee already debited)
Dispute fees are non-refundable regardless of outcome. The best defense against disputes is:
  1. Use 3DS authentication (shifts fraud liability to issuer)
  2. Provide clear billing descriptors
  3. Respond to disputes promptly with evidence
  4. Maintain records of customer transactions and communication

​
Debugging Tips

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