> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider errors

> How Yuno surfaces downstream payment provider errors, the ISO 8583 decline codes you will see, and how to decide whether to retry or fail.

When a payment fails at the provider (the issuer, the acquirer, or the gateway between them), Yuno wraps the failure in its standard error envelope and surfaces the provider's raw response so you can inspect it.

## How provider errors are returned

Errors that originate downstream are returned with a `PROVIDER_*` prefixed `code` in the standard error envelope, and the provider's raw text in `messages`.

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "code": "PROVIDER_INVALID_REQUEST",
  "messages": [
    "Insufficient funds (provider response code 51)"
  ]
}
```

The full set of `PROVIDER_*` codes is documented in [Error codes](/troubleshooting/error-codes#provider-codes). Common ones include `PROVIDER_INVALID_REQUEST`, `PROVIDER_REQUEST_TIMEOUT`, `PROVIDER_PAYMENT_NOT_FOUND`, `PROVIDER_INVALID_AMOUNT`, `PROVIDER_COUNTRY_NOT_SUPPORTED`, `PROVIDER_CURRENCY_NOT_ALLOWED`, and `PROVIDER_UNAVAILABLE_PAYMENT_METHOD`.

For card payments that the issuer declined, retrieve the payment with [Get Payment](/api-reference/payments/get) and inspect the transaction history. Each transaction includes the provider's raw response, including the ISO 8583 decline code.

## Soft vs hard declines

Whether you should retry a card decline depends on the **type** of decline. Soft declines may resolve on their own. Hard declines will not.

| Type             | Description                                     | Retry?                                        | Examples                                           |
| ---------------- | ----------------------------------------------- | --------------------------------------------- | -------------------------------------------------- |
| **Soft decline** | Temporary issue that may resolve.               | Yes, with backoff and a sensible attempt cap. | Insufficient funds, issuer timeout, network error. |
| **Hard decline** | Permanent issue that will not resolve on retry. | No. Surface to the customer.                  | Invalid card number, stolen card, closed account.  |

<Note>
  Retrying hard declines wastes processing capacity and can trigger card network fraud rules. Always classify the decline type before deciding to retry.
</Note>

## Common ISO 8583 decline codes

These are standard codes returned by card issuers and surfaced by every major acquirer. Yuno passes them through verbatim in the transaction response.

### Card declines

| Code | Description                   | Type | Recommended action                                          |
| ---- | ----------------------------- | ---- | ----------------------------------------------------------- |
| `01` | Refer to issuer               | Soft | Ask the customer to contact their bank.                     |
| `02` | Refer to issuer (special)     | Soft | Ask the customer to contact their bank.                     |
| `04` | Pick up card                  | Hard | Do not retry. Card reported lost or stolen.                 |
| `05` | Do not honor                  | Soft | Retry once. If it fails, ask for an alternate method.       |
| `12` | Invalid transaction           | Hard | Verify transaction parameters.                              |
| `13` | Invalid amount                | Hard | Check amount format and provider limits.                    |
| `14` | Invalid card number           | Hard | Ask the customer to re enter card details.                  |
| `41` | Lost card                     | Hard | Do not retry.                                               |
| `43` | Stolen card                   | Hard | Do not retry.                                               |
| `51` | Insufficient funds            | Soft | Inform the customer. Suggest a lower amount or retry later. |
| `54` | Expired card                  | Hard | Ask the customer for a valid card.                          |
| `55` | Incorrect PIN                 | Soft | Ask the customer to re enter the PIN.                       |
| `57` | Transaction not permitted     | Hard | Card type is not allowed for this transaction.              |
| `61` | Exceeds withdrawal limit      | Soft | Suggest a lower amount or retry the next day.               |
| `65` | Activity count limit exceeded | Soft | Retry later.                                                |

### Network and gateway issues

| Code | Description        | Type | Recommended action              |
| ---- | ------------------ | ---- | ------------------------------- |
| `91` | Issuer unavailable | Soft | Retry with exponential backoff. |
| `96` | System malfunction | Soft | Retry after a short delay.      |

For non card methods (PIX, Boleto, OXXO, PSE, SEPA DD, ACH DD, and others), providers do not use ISO 8583 codes. The Yuno `code` will still be a `PROVIDER_*` value and the provider's raw text will be in `messages`. Inspect the message for the provider specific reason.

## MCC restrictions

Some declines relate to the Merchant Category Code (MCC) on your account.

| Scenario                                            | Cause                               | Resolution                                     |
| --------------------------------------------------- | ----------------------------------- | ---------------------------------------------- |
| "Transaction not permitted" for specific card types | MCC restriction by issuer           | Contact Yuno support to verify MCC assignment. |
| High decline rates for certain countries            | MCC flagged for risk in that region | Review with the provider.                      |
| Recurring payment declines                          | MCC not enabled for recurring       | Update MCC configuration.                      |

## Retry strategy

<Steps>
  <Step title="Classify the decline">
    Read the ISO 8583 code (cards) or the provider message (non card) and decide if it is soft or hard using the tables above.
  </Step>

  <Step title="For a soft decline, retry with backoff">
    Use exponential backoff with full jitter. Cap retries at 3 attempts. Do not retry faster than every 1 s.

    ```javascript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
    const SOFT_DECLINES = new Set(["01", "02", "05", "51", "55", "61", "65", "91", "96"]);

    if (SOFT_DECLINES.has(providerResponseCode)) {
      // Retry with exponential backoff and full jitter, max 3 attempts.
    }
    ```
  </Step>

  <Step title="For a hard decline, do not retry">
    Surface a clear message to the customer and offer an alternate payment method.
  </Step>
</Steps>

<Warning>
  Card networks impose retry limits. Mastercard allows up to 10 retries per card per 24 hours. Visa allows up to 15 retries per card per 30 days. Exceeding these limits can result in fines from the network. Track your per card retry counts.
</Warning>

## Escalating provider issues

If you encounter persistent provider errors that are not listed here, open a support ticket with:

* The Yuno `payment_id` and the response `x-trace-id` header.
* The provider name and the raw response code or message.
* Timestamp and frequency.