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

  1. Parse internalStatus from every non-2xx response.
  2. Map to action: retry, surface to user, or escalate (see tables below).
  3. Never retry 409s — they reflect a state conflict that a retry will not resolve.
  4. 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.
  5. For transient failures (network errors, 5xx): retry with exponential backoff. Do not retry 4xx.
  6. 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 CONFLICT response 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

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed request fieldsFix request payload
INVALID_DEPOSIT_INFO400No usable deposit instructions satisfy the requested label and other deposit requirementsCheck the exact, case-sensitive enforceDepositAddressLabel, the user/company address configuration, and the asset, legal entity, and network. See Deposit labels.
INVALID_DESTINATION400Ramp-off destination invalid for selected railValidate bank/wallet details before submitting
INVALID_ADDRESS400Crypto address malformed or invalidRe-validate address client-side
ADDRESS_LOOP400Destination address is one of the user's own deposit addressesUse an external address
EXPIRED_LOCK400Price lock code expiredRequest a new price lock and retry
INVALID_LOCK400Price lock code invalidVerify lock code; request a new one
BLOCKED_UIF400Operation exceeds the identity's available limitDo not retry; check Operational Limits and trigger the raise-limits flow
RISKY_WITHDRAW_ADDRESS403Address flagged by compliance screeningDo not retry; escalate to compliance
USER_NF404User not foundVerify userId or numberId in request
PRICE_LOCK_NF404Price lock not foundRequest a new price lock
USER_NOT_VALIDATED409User has not completed KYC/onboardingBlock operation; direct user to complete verification
USER_BLOCKED409User account blocked by complianceEscalate to compliance review; do not retry
OPERATION_BLOCKED409Asset pair or operation disabled by platform policyNot a limit error. Retry later or contact support
SYNTHETIC_STATUS409Synthetic is in a state that disallows this actionCheck current synthetic status before retrying
SYNTHETIC_EXISTS409Synthetic with same IDs already existsIdempotency 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.

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed fieldsFix request payload
INVALID_COIN400Unsupported assetUse a supported asset — see Coverage
INVALID_NETWORK_FOR_DEPOSIT_REQUEST400Network not available for this asset/countryCheck Coverage for valid network/asset combinations
UNKNOWN_NETWORK400Network identifier not recognizedVerify network string against supported networks
USER_NF404User not foundVerify userId before calling

Assigning a deposit address with POST /crypto/v2/user-actions/assign-deposit-address can return:

internalStatusHTTPDescriptionAction
BAD_REQUEST400A field is missing or invalid; details in errorsFix the request body before retrying
INVALID_DEPOSIT_REQUEST_PARAMS400asset has no deposit addressesUse ARS, BRL, COP or MXN
PERMISSIONS403Deposit addresses are not enabled for your company in the user's countryContact Manteca to enable them
USER_NF404No user matches userAnyIdVerify userAnyId before calling
BANK_ACCOUNT_EXISTS409The user already has a deposit address or a virtual account for assetDo not retry. The existing account is listed in the user's banking.addresses
USER_STATUS409The user is not ACTIVEFinish the user's onboarding first
UNKNOWN_USER409The user has no legalIdComplete the user's identity declaration first
LIVENESS_REQUIRED409Brazil only: the user has not completed the liveness checkComplete the liveness check first
OWNER_CONFLICT409The user's legal ID or national ID is already registered to another account holderDo not retry. Verify the user's legalId and contact Manteca if it is correct

Withdraw Leg

Applies to POST /crypto/v2/withdraws.

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed fieldsFix request payload
NO_FUNDS400Insufficient balanceCheck balance before submitting
INVALID_DESTINATION400Ramp-off destination invalid for selected railValidate bank account details
INVALID_ADDRESS400Crypto address malformed or invalidRe-validate address
ADDRESS_LOOP400Destination address is one of the user's own deposit addressesUse an external address
BLOCKED_UIF400Payout exceeds the sender's available limitDo not retry; check Operational Limits
SENDER_BLOCKED400Declared sender is blocked for remittancesDo not retry; escalate to compliance
RECIPIENT_BLOCKED400Declared recipient is blocked for remittancesDo not retry; escalate to compliance
RISKY_WITHDRAW_ADDRESS403Address flagged by compliance screeningDo not retry; escalate to compliance
USER_NF404User not foundVerify userId
USER_NOT_VALIDATED409User has not completed KYCBlock operation; direct user to verify
USER_BLOCKED409User account blockedEscalate; do not retry
OPERATION_BLOCKED409Asset or operation disabled by platform policyNot 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.

internalStatusHTTPDescriptionAction
INVALID_DOCUMENTATION_FORMAT409File extension not allowed for the requested docTypeUse 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-URL PUT still returns 200, so request a new URL and upload a file whose content matches its extension.


Post-Execution Errors (Withdraw 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.

CodeCategoryDescription
E1GenericGeneric error
E2GenericTransfer reverted (delivered, then returned)
P1PaymentGeneric payment error
P2PaymentPayment rejected
P3PaymentPayment expired
C1AccountGeneric account error
C2AccountBank provided does not match account
C3AccountAccount number does not exist
C4AccountAccount number is inactive or disabled
C5AccountAccount number is invalid
C6AccountAccount currency is invalid
C7AccountBank is not supported
C8AccountAccount type is not valid for bank destination
C9AccountAccount type is invalid
C10AccountAccount did not accept payout in time
D1IdentityDocument number does not match account
D2IdentityDocument number is invalid
D3IdentityDocument number is inactive
U1UserEmail is invalid
U2UserName does not match document
B1BankTransaction is below minimum amount
B2BankBank is invalid
R1ComplianceRejected by compliance
R2ComplianceBreaks 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


Did this page help you?