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:
{
"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.
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 | (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
forClientIdparam.
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 and reviewing withdrawer.availability.reason.
For a deeper explanation of the most common payout failures and how to resolve them, see Common Payout Errors.