Ramps Error Handling
For error response format and general handling, see Key concepts.
Handle ramp errors by combining internalStatus from the API response with the entity's current lifecycle state. Do not rely on HTTP status alone.
Handling Strategy
- Parse
internalStatusfrom every non-2xx response. - Map to action: retry, surface to user, or escalate (see tables below).
- Never retry 409s — they reflect a state conflict that a retry will not resolve.
- For compliance blocks (
BLOCKED_UIF,SENDER_BLOCKED,RECIPIENT_BLOCKED,USER_BLOCKED,RISKY_WITHDRAW_ADDRESS): route to your review/escalation path immediately. These are deterministic — retrying returns the same error. - For transient failures (network errors, 5xx): retry with exponential backoff. Do not retry 4xx.
- On synthetics, also inspect the stages — a synthetic can be created successfully and fail later. See Failures after creation.
Do not retry on 409. A
CONFLICTresponse means the operation is blocked by state (user validation, existing synthetic, disabled asset pair). Retrying will return the same error until the underlying state changes.
Automatic Mode (Synthetics)
Applies to POST /crypto/v2/synthetics/ramp-on and POST /crypto/v2/synthetics/ramp-off.
Creation Errors
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed request fields | Fix request payload |
INVALID_DEPOSIT_INFO | 400 | No usable deposit instructions satisfy the requested label and other deposit requirements | Check the exact, case-sensitive enforceDepositAddressLabel, the user/company address configuration, and the asset, legal entity, and network. See Deposit labels. |
INVALID_DESTINATION | 400 | Ramp-off destination invalid for selected rail | Validate bank/wallet details before submitting |
INVALID_ADDRESS | 400 | Crypto address malformed or invalid | Re-validate address client-side |
ADDRESS_LOOP | 400 | Destination address is one of the user's own deposit addresses | Use an external address |
EXPIRED_LOCK | 400 | Price lock code expired | Request a new price lock and retry |
INVALID_LOCK | 400 | Price lock code invalid | Verify lock code; request a new one |
BLOCKED_UIF | 400 | Operation exceeds the identity's available limit | Do not retry; check Operational Limits and trigger the raise-limits flow |
RISKY_WITHDRAW_ADDRESS | 403 | Address flagged by compliance screening | Do not retry; escalate to compliance |
USER_NF | 404 | User not found | Verify userId or numberId in request |
PRICE_LOCK_NF | 404 | Price lock not found | Request a new price lock |
USER_NOT_VALIDATED | 409 | User has not completed KYC/onboarding | Block operation; direct user to complete verification |
USER_BLOCKED | 409 | User account blocked by compliance | Escalate to compliance review; do not retry |
OPERATION_BLOCKED | 409 | Asset pair or operation disabled by platform policy | Not a limit error. Retry later or contact support |
SYNTHETIC_STATUS | 409 | Synthetic is in a state that disallows this action | Check current synthetic status before retrying |
SYNTHETIC_EXISTS | 409 | Synthetic with same IDs already exists | Idempotency check: fetch existing synthetic instead of creating |
Failures After Creation (Synthetics)
A 201 on creation does not guarantee the operation will complete. A synthetic runs its stages asynchronously, so a ramp can be created successfully, take the deposit, fill the order, and still be rejected by the banking provider at the withdraw stage.
The failure reason is recorded on the stage that failed, in its errors array — not on the synthetic itself. There is no cancellationReason field on a synthetic. Each entry is the mapped provider error from Post-Execution Errors, in the same code: label form carried by the withdraw's statusMessage.
{
"status": "CANCELLED",
"currentStage": 5,
"stages": {
"3": {
"stageType": "WITHDRAW",
"asset": "ARS",
"amount": "131500.00",
"withdrawId": "64f1e9f5b6c7d8e9f0098765",
"errors": ["C3: Account number does not exist"]
},
"4": { "stageType": "REFUND", "fullyRefunded": true, "assetToRefund": "USDT", "amountToRefund": "100.00000000" },
"5": { "stageType": "ORDER_REVERSAL", "orderId": "64f1f0a5b6c7d8e9f0012345" }
}
}A failed withdraw stage is retried for several minutes before the platform gives up. Once it does, the funds are returned automatically: a REFUND stage credits the user back the asset they started with, an ORDER_REVERSAL stage undoes the order, and the synthetic reaches CANCELLED. No action is required on your side to recover the funds.
For a ramp-off cancelled at the withdraw stage, this means the order is reverted and the user recovers the asset they started with — the crypto — credited to their internal balance. Nothing leaves on-chain or to the bank.
Treat CANCELLED on the SYNTHETIC_STATUS_UPDATE webhook as the terminal failure signal, and use the REFUND stage to confirm what was returned and in which asset.
Manual Mode
Deposit Leg
Applies to POST /crypto/v2/deposit-actions/deposit-request.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed fields | Fix request payload |
INVALID_COIN | 400 | Unsupported asset | Use a supported asset — see Coverage |
INVALID_NETWORK_FOR_DEPOSIT_REQUEST | 400 | Network not available for this asset/country | Check Coverage for valid network/asset combinations |
UNKNOWN_NETWORK | 400 | Network identifier not recognized | Verify network string against supported networks |
USER_NF | 404 | User not found | Verify userId before calling |
Assigning a deposit address with POST /crypto/v2/user-actions/assign-deposit-address can return:
internalStatus | HTTP | Description | Action |
|---|---|---|---|
BAD_REQUEST | 400 | A field is missing or invalid; details in errors | Fix the request body before retrying |
INVALID_DEPOSIT_REQUEST_PARAMS | 400 | asset has no deposit addresses | Use ARS, BRL, COP or MXN |
PERMISSIONS | 403 | Deposit addresses are not enabled for your company in the user's country | Contact Manteca to enable them |
USER_NF | 404 | No user matches userAnyId | Verify userAnyId before calling |
BANK_ACCOUNT_EXISTS | 409 | The user already has a deposit address or a virtual account for asset | Do not retry. The existing account is listed in the user's banking.addresses |
USER_STATUS | 409 | The user is not ACTIVE | Finish the user's onboarding first |
UNKNOWN_USER | 409 | The user has no legalId | Complete the user's identity declaration first |
LIVENESS_REQUIRED | 409 | Brazil only: the user has not completed the liveness check | Complete the liveness check first |
OWNER_CONFLICT | 409 | The user's legal ID or national ID is already registered to another account holder | Do not retry. Verify the user's legalId and contact Manteca if it is correct |
Withdraw Leg
Applies to POST /crypto/v2/withdraws.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed fields | Fix request payload |
NO_FUNDS | 400 | Insufficient balance | Check balance before submitting |
INVALID_DESTINATION | 400 | Ramp-off destination invalid for selected rail | Validate bank account details |
INVALID_ADDRESS | 400 | Crypto address malformed or invalid | Re-validate address |
ADDRESS_LOOP | 400 | Destination address is one of the user's own deposit addresses | Use an external address |
BLOCKED_UIF | 400 | Payout exceeds the sender's available limit | Do not retry; check Operational Limits |
SENDER_BLOCKED | 400 | Declared sender is blocked for remittances | Do not retry; escalate to compliance |
RECIPIENT_BLOCKED | 400 | Declared recipient is blocked for remittances | Do not retry; escalate to compliance |
RISKY_WITHDRAW_ADDRESS | 403 | Address flagged by compliance screening | Do not retry; escalate to compliance |
USER_NF | 404 | User not found | Verify userId |
USER_NOT_VALIDATED | 409 | User has not completed KYC | Block operation; direct user to verify |
USER_BLOCKED | 409 | User account blocked | Escalate; do not retry |
OPERATION_BLOCKED | 409 | Asset or operation disabled by platform policy | Not a limit error. Retry later or contact support |
BLOCKED_UIF, SENDER_BLOCKED and RECIPIENT_BLOCKED are only raised when the request declares a third-party recipient — that is what turns the payout into a remittance and triggers the check. Declaring a sender on its own does not: sender only determines whose limit is consumed (the declared sender.legalId, otherwise the user's own). See Third-Party Operations.
Document Uploads
Applies to POST /crypto/v2/documentations/uploadUrl and the upload to the signed URL, used in the raise-limits flow.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_DOCUMENTATION_FORMAT | 409 | File extension not allowed for the requested docType | Use a supported format (for example .pdf, .jpg, .png) |
A file whose content doesn't match its declared extension is deleted after the upload, and no document is created. The signed-URLPUTstill returns200, so request a new URL and upload a file whose content matches its extension.
Post-Execution Errors (Withdraw statusMessage)
statusMessage)After a fiat payout reaches CANCELLED, the statusMessage field contains a structured code from the banking provider identifying the root cause. The same codes apply across all fiat payout flows — ramp-off withdraws, QR payments, and virtual-account collect/disburse (where the code sits on the failing stage's statusMessage).
The field carries the code and its label in a single string, separated by a colon — for example C3: Account number does not exist. Match on the code prefix, not on the full string.
| Code | Category | Description |
|---|---|---|
E1 | Generic | Generic error |
E2 | Generic | Transfer reverted (delivered, then returned) |
P1 | Payment | Generic payment error |
P2 | Payment | Payment rejected |
P3 | Payment | Payment expired |
C1 | Account | Generic account error |
C2 | Account | Bank provided does not match account |
C3 | Account | Account number does not exist |
C4 | Account | Account number is inactive or disabled |
C5 | Account | Account number is invalid |
C6 | Account | Account currency is invalid |
C7 | Account | Bank is not supported |
C8 | Account | Account type is not valid for bank destination |
C9 | Account | Account type is invalid |
C10 | Account | Account did not accept payout in time |
D1 | Identity | Document number does not match account |
D2 | Identity | Document number is invalid |
D3 | Identity | Document number is inactive |
U1 | User | Email is invalid |
U2 | User | Name does not match document |
B1 | Bank | Transaction is below minimum amount |
B2 | Bank | Bank is invalid |
R1 | Compliance | Rejected by compliance |
R2 | Compliance | Breaks same name constraint |
C and D codes indicate a data quality issue with the recipient's account or document — surface them to the user and request corrected details before resubmitting. B1 requires adjusting the transfer amount. P* (payment) codes may be transient. R* codes are compliance rejections — do not retry with the same details; R2 means the counterparty's document must match the account owner. E2 is not a failure — the transfer was delivered and then returned; the reversalId / reversalNationalId fields carry the return's identifiers.
If you encounter a BAD_ESTIMATE error when creating a withdraw lock, it means the cost estimation expired or market conditions changed significantly. Create a new withdraw lock and re-submit — this is transient and typically resolves on retry.
Related Pages
- Coverage — valid country/network/asset combinations
- Operational Limits — limit thresholds and the
BLOCKED_UIFtrigger - Operation Lifecycle Statuses — withdraw and synthetic state machines
Updated 12 days ago