> 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. # Payout API Error Codes ## Payout API Error Codes This page provides a consolidated reference of the error responses returned by the Payout (Withdraw) APIs. Use it to build error decoders and to surface actionable messages to your users. ### Error Response Format When a payout request fails, the API returns a non-2xx HTTP status code. Most payout errors share a simple response body with a single `msg` field describing the reason: ```json { "msg": "Card is not eligible for disbursements" } ``` A small number of endpoints return additional fields (for example, the verification flow returns a `verificationLink`). These are noted in the tables below. > **Note** > > The `msg` string is a human-readable description and may be refined over time. Whenever possible, key your error handling on the combination of the **HTTP status code** and the **endpoint**, and treat `msg` as supplementary context. ### Consolidated Error Reference The following tables enumerate the error responses for each payout endpoint. #### `POST /withdraw/kyc/attested` — Register User Via Attested KYC | HTTP Status | `msg` | Meaning | | ----------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | | 400 | `SSN is required for this merchant` | The merchant requires an SSN and none was provided. | | 400 | `Only supported for the US and BR` | The merchant requires an SSN and the user's `country` is not `US` or `BR`. | | 400 | `SSN is not valid (last 4 numbers)` | Outside `BR`, `ssn` must be exactly 4 digits (the last 4 of the SSN). `BR` accepts the full CPF or CNPJ. | | 400 | `BR tax ID must be at most 14 digits` | For `BR`, `ssn` is the full CPF (11 digits) or CNPJ (14 digits) and cannot exceed 14 digits. | | 422 | *(validation error on `ssn`)* | `ssn` must be digits only (no dots, dashes or spaces). | | 400 | *(address validation message)* | The supplied address could not be validated. The `msg` describes the specific field. | | 401 | *(authentication error)* | Missing or invalid authentication credentials. | | 403 | *(authorization error)* | The caller is not authorized for this merchant. | | 500 | `Failed to validate address` | An unexpected error occurred while validating the address. | #### `GET /session-key` — Get Session Key | HTTP Status | `msg` | Meaning | | ----------- | ------------------------ | ------------------------------------------------------------------ | | 401 | *(authentication error)* | Missing or invalid wallet / merchant authentication. | | 403 | *(authorization error)* | The wallet or merchant is not authorized to request a session key. | #### `GET /withdraw/quote` — Get Quote | HTTP Status | `msg` | Meaning | | ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | | 400 | `Cannot determine currency of card` | The currency for the selected payout method could not be resolved. | | 401 | `User is blocked` | The withdrawer has been blocked (for example, for suspected fraud). | | 404 | `Withdrawer not found` | No withdrawer record exists for the authenticated user. | | 404 | `Merchant {merchantId} not found` | The `merchantId` supplied does not correspond to a known merchant. | | 429 | *(rate limit exceeded)* | Too many quote requests in a short period. Retry after the rate-limit window. | #### `POST /api/withdraw` — Create Withdraw | HTTP Status | `msg` | Meaning | | ----------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | 401 | `User is blocked` | The withdrawer has been blocked and cannot withdraw. | | 402 | `Insufficient Funds` | The source of funds does not have enough balance to cover the withdraw. | | 404 | `Withdrawer not found` | No withdrawer record exists for the authenticated user. | | 409 | `Withdraw Already Pending` | A withdraw for this withdrawer is already in progress. | | 409 | `Idempotency key conflict` | The provided idempotency key has already been used. | | 412 | *(additional details required)* | Additional details (for example, address or bank account details) are required before withdrawing. | | 451 | `User Must Complete Additional Verification` | The withdrawer must complete verification first. The response includes a `verificationLink`. | | 452 | `Instant withdrawals are not available at this time, please select a slower withdraw speed, or try again later` | Instant delivery is temporarily unavailable. | #### `GET /withdraw/history` — Get Withdrawer History | HTTP Status | `msg` | Meaning | | ----------- | ------------------------ | --------------------------------------------------------------- | | 401 | *(authentication error)* | Missing or invalid authentication credentials. | | 403 | *(authorization error)* | The caller is not authorized to view this withdrawer's history. | #### `DELETE /withdraw/account/{token}` — Delete Withdrawer Bank Account | HTTP Status | `msg` | Meaning | | ----------- | ------------------------ | ------------------------------------------------------- | | 401 | *(authentication error)* | Missing or invalid authentication credentials. | | 403 | *(authorization error)* | The caller is not authorized to delete this account. | | 404 | `Withdrawer not found` | No withdrawer record exists for the authenticated user. | #### `DELETE /withdraw/card/{token}` — Delete Withdrawer Card | HTTP Status | `msg` | Meaning | | ----------- | ------------------------ | ------------------------------------------------------- | | 401 | *(authentication error)* | Missing or invalid authentication credentials. | | 403 | *(authorization error)* | The caller is not authorized to delete this card. | | 404 | `Withdrawer not found` | No withdrawer record exists for the authenticated user. | ### Common Payout Error Messages Several `msg` values can be returned across multiple payout endpoints. The most frequently encountered ones are explained below. #### `Card is not eligible for disbursements` The user's card can't receive payouts due to restrictions from the card network, issuing bank, or card type. Even some debit cards aren't eligible unless they meet specific criteria. * **Visa/Mastercard** may support payouts (Visa Direct, Mastercard Send) if enrolled * **Amex/Discover** usually don't support disbursements * **Some prepaid cards** (especially those not linked to a name or account) don't support disbursements * **Cards issued by banks** that block incoming push payments due to internal policy We recommend the user contact their bank to confirm eligibility. #### `Share token is not eligible for you` This error usually indicates a misconfiguration when generating the KYC share token — the token you're passing to Coinflow is invalid or cannot be processed. Check the following: * **Tri-Party Agreement**: Ensure the agreement has been signed by all parties and properly configured with Coinflow's KYC account. * **Correct Client ID**: When generating the share token, make sure you are passing Coinflow's client ID as the `forClientId` param. #### `User is blocked` Typically means the user was flagged for suspected fraud — either on your account or another merchant's in the Coinflow ecosystem. If it's the same user across accounts, they may be globally blocked. You can view the reason in the merchant dashboard or by calling the [Get Withdrawer endpoint](/api-reference/api-reference/withdraw/get-withdrawer) and reviewing `withdrawer.availability.reason`. > **Note** > > For a deeper explanation of the most common payout failures and how to resolve them, see [Common Payout Errors](/guides/payouts/beyond-payouts/common-payout-errors).