Errors and Controls
For error response format and general handling, see Key concepts.
Use a deterministic error-handling policy across CaaS flows. Use internalStatus as the stable key for programmatic handling, not the HTTP status alone.
Retry guidance by error category
| Category | HTTP range | Strategy |
|---|---|---|
| Validation errors | 400 | Fix the payload and retry only after correction. Do not retry the same request. |
| Business/compliance errors | 400, 403 | Require user action or compliance resolution before retrying. |
| Conflict errors | 409 | Do not retry. These reflect a state conflict that a retry will not resolve. |
| Not found | 404 | Verify the ID is correct. If the resource should exist, escalate. |
| Transient/server errors | 5xx | Retry with exponential backoff. Use externalId for idempotency. |
Do not retry on 409. A
CONFLICTresponse means the operation is blocked by current state, such as user validation requirements, existing duplicate operations, or active operational limits. Retrying will return the same error until the underlying state changes.
User creation error codes
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or invalid parameters | Fix request payload |
INVALID_ID_OR_COUNTRY | 400 | legalId invalid or mismatched with country | Check legal ID formats |
BAD_EXTERNAL_ID | 400 | externalId cannot be purely numeric | Add a non-numeric prefix (e.g., user-123) |
USER_EXISTS | 409 | User already exists | Fetch the existing user instead of creating |
INVALID_BANK_ACCOUNT | 400 | Bank account data is invalid | Validate account details |
INACTIVE_ADDRESS | 400 | Bank account is not active | Use an active account |
CUIT_MISMATCH | 400 | Bank account legal ID differs from user legal ID | Ensure account belongs to this user |
COIN_MISMATCH | 400 | Bank account currency does not match asset | Match account currency to declared asset |
BANK_ACCOUNT_EXISTS | 409 | Bank account already registered | Fetch existing account; do not re-register |
Order creation error codes
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or invalid parameters | Fix request payload |
NO_FUNDS | 400 | Insufficient user balance | Check balance before creating order |
EXPIRED_PRICE | 400 | Price lock has expired | Request a new price lock and retry |
MIN_SIZE | 400 | Below minimum order (0.1 USD) | Increase order amount |
INVALID_COIN | 400 | Asset not supported | Use a supported asset |
INVALID_COIN_COUNTRY | 400 | Asset not available in user's country | Check coverage |
BLOCKED_UIF | 400 | User's operation limit exhausted | Wait for limit reset or escalate |
IS_PEP | 400 | PEP documentation required | Direct user to complete PEP task |
USER_NF | 404 | User not found | Verify userId |
PRICE_NF | 404 | Price not found for pair | Check ticker is valid |
USER_BLOCKED | 409 | User account is blocked | Escalate to compliance; do not retry |
USER_NOT_VALIDATED | 409 | User has not completed onboarding | Direct user to complete KYC |
ORDER_EXISTS | 409 | Duplicate externalId | Fetch the existing order; do not re-create |
OPERATION_BLOCKED | 409 | Operation blocked by policy or limits | Check operational limits; escalate |
Withdraw request-time error codes
internalStatus | HTTP | Description | Action |
|---|---|---|---|
NO_FUNDS | 400 | Insufficient balance | Check balance before submitting |
INVALID_ADDRESS | 400 | Withdraw address is malformed | Validate address client-side |
INVALID_DESTINATION | 400 | Destination invalid for selected rail | Validate bank/wallet details |
RISKY_WITHDRAW_ADDRESS | 403 | Address flagged by compliance | Do not retry; escalate to compliance team |
USER_NF | 404 | User not found | Verify userId |
WITHDRAW_EXISTS | 409 | Duplicate externalId | Fetch the existing withdraw; do not re-create |
OPERATION_BLOCKED | 409 | Withdrawals are blocked | Check limits; escalate if needed |
Idempotency with externalId
Every order, withdraw, and deposit request accepts an optional externalId field. Use it to implement idempotent operation creation:
- Set
externalIdto your internal reference ID (e.g.,order-ref-00441). - If you retry a request that already succeeded, the API returns a 409 instead of creating a duplicate:
ORDER_EXISTSfor orders,WITHDRAW_EXISTSfor withdraws. - A retry sent while the first request is still being processed returns
DUPLICATE_REQUEST(400). Wait, then fetch the resource byexternalId. - On a 409 with a duplicate-ID error, fetch the existing resource by
externalIdand use its current state.
externalId must not be purely numeric. Use a string prefix (e.g., order-, wdr-) to distinguish it from internal numeric IDs.
Recommended controls
- Set
externalIdon every operation creation call. - Persist operation IDs and statuses in your own database at creation time.
- Build webhook handlers as idempotent consumers: receiving the same event twice must not produce duplicate state changes.
- Reconcile periodically using
GET /crypto/v2/stats/balance-activitiesandGET /crypto/v2/orders.
For endpoint-level behavior, see the API Reference, Ramps error handling, and Reconciliation & Reporting.
Updated 27 days ago