> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flouci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Dictionary

> Card payment error codes, what they mean, and how to handle them.

When a card payment is declined, the card processing platform returns an error code and a short message. This page lists the codes observed in production, explains what each one means, and gives the action we recommend for your customer.

<Info>
  **Note:** The message in the **Message returned** column is passed through exactly as the processing platform sends it, in English. The list below is built from refusals observed in production — the platform may return other codes that are not listed here. If you hit one, [contact support](/essentials/debug-support) with the order reference.
</Info>

### Error codes

Use your browser's find (`Ctrl` / `Cmd` + `F`) to jump to a code.

| Code | Message returned (verbatim) | What it means | Recommended action |
| - | - | - | - |
| `-2019` | `Decline by iReq in PARes` | 3-D Secure authentication was refused by the issuing bank during verification. | Offer the customer a new payment attempt, or another card. |
| `-2018` | `Declined. DS connection timeout` | Timeout while connecting to the 3-D Secure authentication service. | Temporary incident. Ask the customer to try again in a few minutes. |
| `-2013` | `Customer has no more payment attempts left on this order number` | The number of payment attempts allowed for this order has been used up. | Do not retry on the same order — create a new payment. |
| `-2007` | `Order expired after session time limit/Customer did not complete the authentication in timely manner` | The payment session expired before the customer completed authentication. | Create a new payment. Consider a longer session duration if this happens often. |
| `-2006` | `Issuer Rejected Authentication - card not authenticated/account not verified/transaction denied, ARES.STATUS = N [TDS_AUTH_FAILED]` | The issuing bank did not authenticate the cardholder. | Offer the customer a new payment attempt, or a card enrolled in 3-D Secure. |
| `76` | `Rejected Authorization - Issuer bank is not able to process the transaction Cannot process transaction]` | The issuing bank is unable to process the transaction. | Temporary incident on the bank side. Ask the customer to try again later. |
| `100` | `Rejected Authorization - Card Limit Exceed [Limit exceeded]` | The card limit has been reached. | Tell the customer their card limit is reached and offer another card. |
| `103` | `Contact issuer.` | The issuing bank is asking the cardholder to contact it. | Ask the customer to contact their bank before retrying. |
| `106` | `PIN attempts exceeded. Card is blocked.` | Too many incorrect PIN entries: the card is blocked. | Tell the customer their card is blocked and offer another card. |
| `110` | `Rejected Authorization - Invalid amount [Invalid amount]` | The amount sent is not valid. | Check the amount format and the currency unit. Contact Flouci support if the problem persists. |
| `111` | `Decline. Wrong PAN` | The card number sent is incorrect. | Ask the customer to check their card number. |
| `116` | `Rejected Authorization - Low Balance [116: Not enough money]` | The card balance is insufficient. | Tell the customer the balance is too low and offer another card. |
| `117` | `processing.error.117` | A processing error returned by the gateway, with no detailed description. | Report the case to Flouci support with the order reference. |
| `119` | `Security violation` | The request was rejected for security reasons. | Report the case to Flouci support with the order reference. |
| `120` | `Rejected Authorization - restricted transaction [Transaction was refused]` | The transaction is refused: this operation is not allowed on this card. | Tell the customer the payment was refused and offer another card. |
| `121` | `Rejected Authorization - Limit Exceed [Limit exceeded]` | The authorized limit was exceeded. | Tell the customer their card limit is reached and offer another card. |
| `125` | `Rejected Authorization - Invalid card number [Invalid card number]` | The card number is not valid. | Ask the customer to check their card number. |
| `903` | `Limit exceeded.` | The authorized limit was exceeded. | Tell the customer their card limit is reached and offer another card. |
| `904` | `Invalid message format` | The request sent to the gateway is not correctly formed. | Check the parameters sent to the API. Contact Flouci support if the problem persists. |
| `910` | `Rejected Authorization - Issuer bank not available [Cannot contact bank]` | The issuing bank could not be reached. | Temporary incident. Ask the customer to try again in a few minutes. |
| `913` | `Invalid message format.` | The request sent to the gateway is not correctly formed. | Check the parameters sent to the API. Contact Flouci support if the problem persists. |
| `2003` | `Non-3DS is not allowed - SSL_FORBIDDEN` | A transaction without 3-D Secure authentication was submitted, and it is not allowed. | Contact Flouci support: the merchant account configuration needs to be checked. |
| `100700` | `Challenge was cancelled by the issuer. Authentication has not been sent to Stand-In` | The issuing bank cancelled the authentication step. | Offer the customer a new payment attempt, or another card. |
| `100801` | `Rejected Authorization - Response not received from SvFE [Timer time out]` | No response was received from the card network within the allotted time. | Check the final state of the order before retrying, to avoid a double debit. |
| `100827` | `Rejected Authorization [Do not honor transaction]` | The issuing bank refused the authorization without giving a reason. | Show a generic refusal message. Invite the customer to retry or use another card. |
| `151018` | `EPG Acquirer is not connected to SvFE [CANNOT_SEND_REQUEST]` | The card network is temporarily unreachable. | Temporary incident on the platform side. Ask the customer to try again later. |
| `151019` | `Payment failed. Cann't connect to Payment Gate.` | The connection to the payment gateway failed. | Temporary incident on the platform side. Ask the customer to try again later. |
| `341016` | `Issuer Rejected Authentication - card not authenticated, ARES.STATUS = R [3DS2 authentication is declined by Authentication Response (ARes)]` | The issuing bank refused the 3-D Secure authentication. | Offer the customer a new payment attempt, or another card. |
| `341017` | `Authentication status in ARes is unknown, ARES.STATUS = U` | The result of the 3-D Secure authentication is undetermined. | Temporary incident. Offer the customer a new payment attempt. |
| `341018` | `Issuer Rejected Authentication - Authentication cancelled by customer, RREQ/CRES.STATUS = N [3DS2 CReq cancelled]` | The customer cancelled the 3-D Secure authentication. | This is not a card refusal: simply offer to restart the payment. |
| `341019` | `Issuer Rejected Authentication - CREQ/CRES has error [3DS2 CReq failed]` | An error occurred during the 3-D Secure authentication exchange. | Temporary incident. Offer the customer a new payment attempt. |
| `341020` | `Issuer Rejected Authentication - RREQ.STATUS = U or R [3DS2 unknown status in RReq]` | The 3-D Secure authentication result is unknown or rejected. | Temporary incident. Offer the customer a new payment attempt. |
| `341022` | `Issuer Rejected Authentication - TimeOut ACS bcz customer did not provide OTP with in 10 minutes` | The customer did not enter their verification code (OTP) within the 10-minute window. | This is not a card refusal: simply offer to restart the payment. |
| `341023` | `Issuer Rejected Authentication - TimeOut ACS bcz OTP page is not opened to customer with in 30 Secs` | The verification code (OTP) page did not open within the allotted time. | This is not a card refusal: simply offer to restart the payment. |
| `341024` | `Issuer Rejected Authentication - Exceed OTP attempts` | The customer exceeded the number of allowed verification code (OTP) entries. | This is not a card refusal: simply offer to restart the payment. |
| `341025` | `Issuer Rejected Authentication - CAVV is not generated by issuer, RREQ.STATUS = N` | The issuing bank did not generate the 3-D Secure authentication certificate. | Offer the customer a new payment attempt, or another card. |
| `342034` | `Operation cancelled by user` | The customer cancelled the operation. | This is not a card refusal: simply offer to restart the payment. |

### Handling patterns

Most of the codes above fall into one of the following patterns. If you only implement one behaviour per pattern, implement these.

<AccordionGroup>
  <Accordion title="An ordinary decline — offer another card">
    `-2019`, `-2006`, `100`, `103`, `106`, `110`, `111`, `116`, `120`, `121`, `125`, `903`, `100700`, `100827`, `341016` and `341025` are refusals of that specific card: insufficient balance, limit reached, blocked card, wrong number, or an issuer refusal. Show the refusal and invite the customer to pay with a different card. Do not reveal why the issuer refused beyond what the table suggests.
  </Accordion>

  <Accordion title="Never retry on the same order">
    `-2013` and `-2007` mean the order itself is finished — the attempt budget is spent, or the session expired. Retrying the same `payment_id` will keep failing. Create a new payment instead.
  </Accordion>

  <Accordion title="Verify before retrying, to avoid a double debit">
    `100801` means the card network never answered within the timeout, so the outcome is genuinely unknown — the customer may have been debited. Always check the final state of the order with [Verify Payment](/api-reference/verify-transaction) before offering a retry.
  </Accordion>

  <Accordion title="Temporary — a retry is likely to succeed">
    `-2018`, `76`, `910`, `151018`, `151019`, `341017`, `341019`, `341020` are timeouts or unreachable-service errors on the bank or platform side. Show a "please try again shortly" message rather than a refusal.
  </Accordion>

  <Accordion title="Not a refusal — the customer simply stopped">
    `341018`, `341022`, `341023`, `341024`, `342034` mean the customer cancelled or let the 3-D Secure step time out. The card is fine. Offer to restart the payment without suggesting anything is wrong with their card.
  </Accordion>
</AccordionGroup>

## Recurring payments error codes

The [Recurring Payments](/api-reference/recurring-payments/overview) endpoints report refusals with the HTTP status below and a code: in `result.error` on **Create**, in `message` on the other endpoints. A field that fails validation on Create is returned as `{"<field>": ["<reason>"]}` without a code. These are API-level refusals, not card declines.

| HTTP | `message` | Endpoint | What it means | Recommended action |
| - | - | - | - | - |
| `400` | field `currency` | Create | `currency` is not `TND`. | Send `TND` — subscriptions are TND only. |
| `400` | field `destination` | Create | A split-payment `destination` was attached to a subscription. | Remove `destination`. |
| `400` | field `interval_count` | Create | `interval` × `interval_count` exceeds one year (366 days · 52 weeks · 12 months · 1 year). | Shorten the cycle. |
| `400` | `card_recurring_not_enabled` | Create | `accept_card: true` while card recurring is not enabled on your affiliation. | Create a wallet subscription (omit `accept_card`) or contact your Flouci contact. |
| `400` | `card_recurring_not_implemented` | Create | Card recurring is enabled for you but not yet live. | Create a wallet subscription for now. |
| `400` | `invalid_subscription_id` | Get, Charges, Cancel | The `subscription_id` in the path is malformed. | Use the value returned by Create Subscription. |
| `403` | `merchant_not_allowed` | Create, List | Your merchant account does not have developer API access. | [Contact support](/essentials/debug-support). |
| `403` | `merchant_wallet_inactive` | Create | Your merchant wallet is inactive. | [Contact support](/essentials/debug-support). |
| `403` | `affiliation_inactive` | Create | Your card affiliation is inactive. | [Contact support](/essentials/debug-support). |
| `404` | `subscription_not_found` | Get, Charges, Cancel | No subscription with this id belongs to your merchant. | Check the id. Another merchant's id is never disclosed. |
| `409` | `duplicate_developer_tracking_id` | Create | A subscription with this `developer_tracking_id` already exists; its ids are in the body. | Treat as success and use the returned `subscription_id` and `link`. |
| `409` | `subscription_terminal` | Cancel | The subscription is already `canceled` or `incomplete_expired`. | Nothing to do. |
| `409` | `subscription_not_active` | Cancel | `at_period_end: true` on a subscription that is not `active` or `past_due`. | Cancel immediately instead. |
| `429` | — | Create | More than 60 creations per minute for this app. | Back off and retry. |
| `503` | `recurring_payments_disabled` | Create | Recurring payments are temporarily paused platform-wide. | Retry later; existing subscriptions are deferred, not failed. |

Two refusals happen on the customer's side, in the Flouci app, and never reach your API: `consent_required` (the app did not present the current consent text) and `subscription_not_payable` (the first charge is no longer payable, for example after you canceled). Both leave the subscription untouched.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.