> ## Documentation Index > Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes > Payment error codes returned by the Axra API 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: ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "statusCode": 409, "message": "Business profile already exists for this user", "error": "Conflict" } ``` **Common causes:** * Attempting to create a duplicate business profile *** ## Dispute-Related Errors 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: 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](./api-reference.md#testing) 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`.