⚠️ 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:

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

Example Response

1
{
2
  "message": "Validation Failed",
3
  "details": {
4
    "address.country": {
5
      "message": "maxLength 2",
6
      "value": "USA"
7
    },
8
    "feePercentage": {
9
      "message": "max 100",
10
      "value": 150
11
    }
12
  },
13
  "debugId": "9d3698c43eda078c793c65b50fd05c90"
14
}

Common Checkout Errors

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 authOnly with a transaction: Authorization-only purchases (authOnly: true) cannot be combined with a redemption transaction. When authOnly is enabled, the payment is only authorized but not captured, which means credits are not minted until the payment is captured. However, the redemption flow expects credits to be available immediately after the card payment.

  Solution: Either remove the transaction parameter and handle redemption separately after capturing the payment, or remove authOnly to capture the payment immediately.

• 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.

Rate Limiting & Velocity Errors

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

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:

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 429 with the message above. This is a Coinflow velocity decision — there is no fraud-provider-specific code returned for this rule.

Card Reuse Errors

3D Secure (3DS) Errors

CVV Revalidation Error

Sandbox Errors