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

CategoryHTTP rangeStrategy
Validation errors400Fix the payload and retry only after correction. Do not retry the same request.
Business/compliance errors400, 403Require user action or compliance resolution before retrying.
Conflict errors409Do not retry. These reflect a state conflict that a retry will not resolve.
Not found404Verify the ID is correct. If the resource should exist, escalate.
Transient/server errors5xxRetry with exponential backoff. Use externalId for idempotency.

🚧

Do not retry on 409. A CONFLICT response 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

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or invalid parametersFix request payload
INVALID_ID_OR_COUNTRY400legalId invalid or mismatched with countryCheck legal ID formats
BAD_EXTERNAL_ID400externalId cannot be purely numericAdd a non-numeric prefix (e.g., user-123)
USER_EXISTS409User already existsFetch the existing user instead of creating
INVALID_BANK_ACCOUNT400Bank account data is invalidValidate account details
INACTIVE_ADDRESS400Bank account is not activeUse an active account
CUIT_MISMATCH400Bank account legal ID differs from user legal IDEnsure account belongs to this user
COIN_MISMATCH400Bank account currency does not match assetMatch account currency to declared asset
BANK_ACCOUNT_EXISTS409Bank account already registeredFetch existing account; do not re-register

Order creation error codes

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or invalid parametersFix request payload
NO_FUNDS400Insufficient user balanceCheck balance before creating order
EXPIRED_PRICE400Price lock has expiredRequest a new price lock and retry
MIN_SIZE400Below minimum order (0.1 USD)Increase order amount
INVALID_COIN400Asset not supportedUse a supported asset
INVALID_COIN_COUNTRY400Asset not available in user's countryCheck coverage
BLOCKED_UIF400User's operation limit exhaustedWait for limit reset or escalate
IS_PEP400PEP documentation requiredDirect user to complete PEP task
USER_NF404User not foundVerify userId
PRICE_NF404Price not found for pairCheck ticker is valid
USER_BLOCKED409User account is blockedEscalate to compliance; do not retry
USER_NOT_VALIDATED409User has not completed onboardingDirect user to complete KYC
ORDER_EXISTS409Duplicate externalIdFetch the existing order; do not re-create
OPERATION_BLOCKED409Operation blocked by policy or limitsCheck operational limits; escalate

Withdraw request-time error codes

internalStatusHTTPDescriptionAction
NO_FUNDS400Insufficient balanceCheck balance before submitting
INVALID_ADDRESS400Withdraw address is malformedValidate address client-side
INVALID_DESTINATION400Destination invalid for selected railValidate bank/wallet details
RISKY_WITHDRAW_ADDRESS403Address flagged by complianceDo not retry; escalate to compliance team
USER_NF404User not foundVerify userId
WITHDRAW_EXISTS409Duplicate externalIdFetch the existing withdraw; do not re-create
OPERATION_BLOCKED409Withdrawals are blockedCheck 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 externalId to 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_EXISTS for orders, WITHDRAW_EXISTS for withdraws.
  • A retry sent while the first request is still being processed returns DUPLICATE_REQUEST (400). Wait, then fetch the resource by externalId.
  • On a 409 with a duplicate-ID error, fetch the existing resource by externalId and 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 externalId on 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-activities and GET /crypto/v2/orders.

For endpoint-level behavior, see the API Reference, Ramps error handling, and Reconciliation & Reporting.


Did this page help you?