> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# ⚠️ Common Errors

### Request Validation Errors

When a checkout request is missing a required field, or a field's value falls outside the type, length, or range the API expects, the request is rejected before checkout processing begins. The API returns an HTTP `422` response.

The response body contains the following fields:

| Field     | Type   | Description                                                |
| --------- | ------ | ---------------------------------------------------------- |
| `message` | string | Always `"Validation Failed"` for this error type.          |
| `details` | object | A map of the invalid field's path to its validation error. |
| `debugId` | string | A unique identifier for debugging purposes.                |

Each entry in `details` is keyed by the field path and contains:

| Field     | Type   | Description                                               |
| --------- | ------ | --------------------------------------------------------- |
| `message` | string | Describes why the field failed validation.                |
| `value`   | any    | The value that was submitted for the field, if available. |

#### Example Response

```json
{
  "message": "Validation Failed",
  "details": {
    "address.country": {
      "message": "maxLength 2",
      "value": "USA"
    },
    "feePercentage": {
      "message": "max 100",
      "value": 150
    }
  },
  "debugId": "9d3698c43eda078c793c65b50fd05c90"
}
```

> **Warning**
>
> Validation details may vary depending on the specific validation context. The `details` field is provided for additional context and should not be relied on as a stable error format.

### Common Checkout Errors

| Error Message                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                              | Code |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `User is blocked`                                                  | Occurs when a customer has raised or is about to raise a chargeback using the same card—either on your account or with any merchant in the Coinflow ecosystem. This helps prevent repeated fraud or misuse across the platform and is triggered by both formal chargebacks and pre-chargeback notifications.                                                                                             | 400  |
| `No Customer Associated with Customer ID`                          | Expected for a first-time payer. Coinflow creates a customer record after the payer completes their first purchase. The payment method is saved, so the next time the customer returns, their payment method will be automatically available for a faster checkout. A returning customer who has already made a purchase through Coinflow will not encounter this error.                                 | 400  |
| `Invalid merchant configuration - credit settlement not supported` | Appears when a purchase for Credits doesn't align with the merchant's setup. Confirm you're intending to buy Credits, and ensure you're passing the correct headers for your settlement configuration. See [authentication headers](/api-reference/api-reference/authentication/get-session-key) for the headers required by your settlement setup.                                                      | 400  |
| `Please sign a message and get a JWT token to use this endpoint`   | A signed JWT is required to authorize access to saved payment methods. Use the [Get Session Key endpoint](/api-reference/api-reference/authentication/get-session-key) and pass the returned sessionKey to the CoinflowPurchase component (as a prop) or in the x-coinflow-auth-session-key header. **Note: Ensure you're passing the correct headers for your use case when generating a session key.** | 400  |

\


#### Advanced: Settling to an EVM Contract

| Error Message                                                       | Description                                                                                                                                                                                                                                    | Code |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `Address: call to non-contract`                                     | Typically returned when merchants are settling revenue to an EVM contract on a sandbox environment. Make sure `transactionData.transaction.to` is set to your testnet contract address—not your mainnet address if you are testing in sandbox. | 400  |
| `Insufficient allowance`                                            | Typically returned when a contract other than the one whitelisted is trying to pull the funds from coinflow contract. Ensure you've whitelisted your contract and are passing the correct address to `transactionData.transaction.to`.         | 400  |
| `Insufficient USDC allowance` / `Transfer amount exceeds allowance` | Typically returned when a merchant contract is trying to pull more USDC from our contract than what Coinflow's contract approved for it to spend.                                                                                              | 400  |

\


### Invalid Configuration Errors

##### `Payments not configured correctly, please contact merchant`

This error appears when an invalid combination of checkout parameters is used. Common causes include:

* **Using a `transaction` with non-Credits settlement**: Redemption transactions can only be used with `settlementType: "Credits"`. The `transaction` parameter triggers a credit redemption flow where credits are issued to the user and then redeemed via your custom redemption flow. This flow is incompatible with USDC or Bank settlement types.

  **Solution**: Set `settlementType` to `"Credits"` when using a `transaction`, or remove the `transaction` parameter if you need a different settlement type.

| Error Message                                                | Code |
| ------------------------------------------------------------ | ---- |
| `Payments not configured correctly, please contact merchant` | 400  |

\


### Velocity & Attempt Limit Errors

These errors are triggered by repeated failed attempts on the same account, card, or session in a short window.

| Error Message                                                                                                                               | Description                                                                                                                                                              | Code                  |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| `Failed checkout attempts exceeded limit (N), please try again later`                                                                       | Returned when an account has exceeded the allowed number of failed checkout attempts. Wait for the cooldown period to pass, then retry.                                  | 400                   |
| `Payment attempts with multiple cards have failed. For security, please wait 1 hour before trying again.`                                   | Returned when a customer has attempted payment with several different cards that all failed. For security, the customer must wait one hour before trying again.          | 400                   |
| `This account has reached its card limit for the past 30 days. Please use a card you have used before or try again later.`                  | Returned when an account has attempted payment with too many distinct cards within a rolling 30 day window. Use a previously used card, or wait before adding a new one. | 400                   |
| `We are unable to process your payment at this time.`                                                                                       | A generic decline returned when a payment is rejected by Coinflow's velocity checks. Retrying after some time, or with a different payment method, may succeed.          | 400                   |
| `This Visa card has reached its maximum number of retry attempts (N) over the past 30 days. Please try a different card or payment method.` | Returned when a specific Visa card has been declined too many times in the past 30 days. Use a different card or payment method.                                         | 400 (auth code `100`) |

\


#### Distinct card limit (max cards per customer)

The **Max distinct cards per customer (30d)** rule caps how many
*distinct card tokens* a single customer may use with your merchant account within a
**rolling 30-day window**. When a customer exceeds the cap, the checkout is rejected with:

| Error Message                                                                                                              | Code |
| -------------------------------------------------------------------------------------------------------------------------- | ---- |
| `This account has reached its card limit for the past 30 days. Please use a card you have used before or try again later.` | 400  |

The numeric cap is intentionally omitted from the customer-facing message so it can't be
probed. The exact configured value is available to Coinflow support in the transaction logs.

**How the rule counts cards**

* Only **distinct card tokens** are counted, deduplicated per token — a customer reusing the
  same card any number of times still counts as one card.
* Only **non-failed** payments count. Payments in a `Failed` or `Voided` state are excluded
  from the total.
* The window is a **rolling 30 days**, evaluated at charge time.

**Apple Pay / Google Pay**

Apple Pay and Google Pay transactions are **excluded** from this rule. Wallet payments are
not counted toward the distinct-card total and never trigger this block, because the device
token used by a wallet is not a stable identifier for a physical card.

**Subscriptions / merchant-initiated (MIT) renewals**

Merchant-initiated renewals **skip the check at charge time** so a recurring subscription is
never blocked mid-cycle, but the card used **still counts** toward the customer's distinct-card
total for subsequent customer-initiated checkouts.

**Applying the rule to existing vs. new customers**

There is **no "new customers only" toggle**. To avoid blocking established customers who already
hold more cards than the configured limit, use one of the following:

* Set a **per-customer distinct-token override** for the legacy customer to raise
  their individual cap, or
* Mark the customer as **exempt from failed-attempt checks** (`failedAttemptSetting: Exempt`),
  which bypasses this rule entirely for that customer.

**Error / provider code returned**

A blocked checkout returns **HTTP 400** with the message above. This is a Coinflow velocity
decision — there is **no fraud-provider-specific code** returned for this rule.

\


### Card Reuse Errors

| Error Message                                                              | Description                                                                                                       | Code |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---- |
| `Card already exists for another user, please use a different card`        | Returned when a customer attempts to save a card that is already associated with a different customer record.     | 400  |
| `This card has already been used by another customer and cannot be reused` | Returned when a card has already been used by another customer and card reuse is not permitted for this merchant. | 403  |

\


### 3D Secure (3DS) Errors

| Error Message                                          | Description                                                                                                                                                                                                | Code                  |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `Challenge required`                                   | Returned when the issuer requires the customer to complete a 3DS challenge before the payment can proceed. The response includes `transactionId`, `url`, and `creq` fields needed to render the challenge. | 412                   |
| `Card rejected by issuer`                              | Returned when the issuing bank rejects the 3DS authentication request outright.                                                                                                                            | 400 (auth code `998`) |
| *(varies — issuer-supplied challenge failure message)* | Returned when the customer starts but fails to complete the 3DS challenge (for example, entering an incorrect one-time code). The customer should retry the purchase or try a different card.              | 400 (auth code `997`) |

\


### CVV Revalidation Error

| Error Message                                                                                                                                                                     | Description                                                                                                                                                   | Code |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `Validation for this card has expired. Revalidate the CVV for this card, and make a new purchase using the /api/checkout/card/token in order to begin using this endpoint again.` | Returned when a previously validated card's CVV validation has expired. Revalidate the CVV via `/api/checkout/card/token` before reusing this payment method. | 410  |

\


### Sandbox Errors

| Error Message                                            | Description                                                                                                                            | Code |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `Purchases are limited to $N in the sandbox environment` | Returned when a purchase in the sandbox environment exceeds the fixed sandbox purchase limit. This limit does not apply in production. | 400  |