Error handling

For error response format and general handling, see Key concepts.

Handle Virtual Accounts errors by parsing internalStatus from every non-2xx response. Do not rely on HTTP status alone. message strings are fixed English text and may change — always key logic and user-facing display off internalStatus.


User onboarding errors

Applies to POST /wallet/v1/onboarding-actions/*.

internalStatusHTTPDescriptionAction
BAD_REQUEST400Validation failed on one or more fieldsSee the errors[] array for field details
USER_NF404userAnyId not foundVerify the user ID
USER_EXISTS409A user with that legal ID already existsIdempotency check: fetch the existing user
USER_EXISTS_EMAIL409A user with that email already existsUse a different email or fetch the user
PERSON_EXISTS409That legal ID is already declared under a different user in this companyIdempotency check: fetch the existing user by legalId

Account creation errors

Applies to POST /wallet/v1/user-actions/assign-virtual-account.

internalStatusHTTPDescriptionAction
BAD_REQUEST400Validation failed on one or more fieldsSee the errors[] array for field details
PERMISSIONS403Company is not enabled for Virtual Accounts in this user's countryContact support to enable wallet clearance
USER_STATUS409User is not active on the wallet platformVerify user is fully onboarded and active
UNKNOWN_USER409User has no legalId yet (identity declaration incomplete)Complete identity declaration before requesting an account
BANK_ACCOUNT_EXISTS409User already has a virtual account for this assetIdempotency check: fetch the existing account for that asset
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

Do not retry on 409. These reflect a state that must change before the operation can succeed.


Company onboarding errors

Applies to POST /wallet/v1/onboarding-actions/simple when type is BUSINESS, and to POST /wallet/v1/onboarding-actions/define-personal-data (also POST /crypto/v2/onboarding-actions/define-personal-data) for a BUSINESS user. The 400s below are validated synchronously — fix the payload and resubmit. CANT_MODIFY_BENEFICIARIES is not a payload problem, so resubmitting a corrected payload does not help.

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed corporate / shareholder fieldsFix request payload
INVALID_SHAREHOLDERS400shareholders empty, or participationPercentage sum exceeds 100Ensure at least one shareholder and Σ ≤ 100
INVALID_REPRESENTATIVES400A legal representative is missing required data, a CNPJ shareholder has no representative while more than one is declared, or representedBy points at a representative that cannot act for that shareholderComplete each representative, and send representedBy on every CNPJ shareholder when the company declares more than one representative
CONFLICTING_EXTERNAL_ID400The same legalId (a person in more than one role) was given different externalId valuesUse the same externalId — or none — for a person that appears as both a shareholder and a representative
CANT_MODIFY_BENEFICIARIES409The company already has a persisted set of legal representatives, and this call tried to add, remove or swap oneDo not retry with a changed set. Resend the exact same persisted set of representatives (by legalId) if you only need to correct other company data

Transfer errors

Applies to POST /wallet/v1/transfers. Returned synchronously (non-2xx): the transfer is never created and no funds move.

internalStatusHTTPDescriptionAction
BAD_REQUEST400Validation failed on one or more fieldsSee the errors[] array for field details
NO_FUNDS400Insufficient balance on the sender accountCheck balance before submitting
ACCOUNT_NOT_FOUND404Sender account not foundVerify account address
INVALID_ACCOUNT404Sender account exists but has no usable addressContact support
TRANSFER_EXISTS409Transfer with same id already existsIdempotency check: fetch existing transfer
PAYMENT_DESTINATION_AMOUNT_MISMATCH400amount differs from the amount fixed by the QR codeSend the QR code's amount, as returned by GET /wallet/v1/address-info
PAYMENT_DESTINATION_NOT_FOUND409The QR code was already paid or has expiredDo not retry; request a new QR code from the recipient

Do not retry on 409. These reflect a state that must change before the operation can succeed.


Collect and disburse errors

For the collect and disburse synthetics, errors surface at creation time — returned synchronously (non-2xx) from POST /wallet/v1/synthetics/collect and POST /wallet/v1/synthetics/disburse. The synthetic is never created and no funds move.

internalStatusHTTPDescriptionAction
BAD_REQUEST400Validation failed on one or more fieldsSee the errors[] array for field details
MASTER_VA_LOOP400The resolved virtual account is the company's own master accountDo not retry; verify the userAnyId
USER_NF404userAnyId not foundVerify the user ID
BANK_ACCOUNT_NF404User has no virtual account for the requested assetAssign a virtual account for the asset first
SYNTHETIC_EXISTS409A synthetic with the same idempotency key already existsIdempotency check: fetch the existing synthetic

Do not retry on 409. These reflect a state that must change before the operation can succeed.


Post-execution failures

Failures after acceptance arrive asynchronously. When a transfer stage fails, the synthetic moves to CANCELLED and the SYNTHETIC_STATUS_UPDATE webhook carries a typed statusMessage on the failing stage, formatted as <code>: <description>. For a disburse stage-2 failure, funds have already been returned to the master account via the added reverse stage — no recovery action is required.

A QR payment sent through POST /wallet/v1/transfers that fails after acceptance moves to CANCELLED with the code in genericErrorMessage, and the debited amount goes back to the virtual account. It is not retried: check the QR code again with GET /wallet/v1/address-info before paying it again.

These are the same banking-provider codes used across every fiat payout flow. Use the prefix to decide whether to retry:

Code prefixCategoryRetry guidance
E1Generic errorPotentially transient — safe to retry once
P1–P3Payment rejected or expiredPotentially transient — retry-able
C1–C10Destination account problemsDo not retry as-is; fix the destination key
D1–D3Document (CPF/CNPJ) mismatchDo not retry as-is; fix the recipient's legal ID
U1–U2Recipient data (email, name) invalidDo not retry as-is; fix the recipient data
B1–B2Destination bank (min amount, invalid)Adjust the amount or use another bank
R1–R3Rejected by complianceDo not retry as-is; see the compliance codes below

Compliance rejection codes (R)

Compliance evaluates a Virtual Account transfer after it is accepted, so these arrive asynchronously — the payout moves to FAILED, and an over-limit or same-name deposit is returned to the sender instead of being credited. A returned deposit does not carry the R code: it arrives as CANCELLED with E2: Transfer reverted (see Same-name enforcement).

CodeDescriptionAction
R1Rejected by complianceGeneric compliance rejection; contact support if it persists
R2Breaks same name constraintThe counterparty's legal ID does not match the account owner's; use an account in the owner's name
R3Exceeds virtual account limitsThe transfer does not fit the remaining allowance; see Operational Limits and the raise-limits flow

See Ramps → Post-Execution Errors for the full per-code list.

For plain transfers, use GET /wallet/v1/transfers/{transferAnyId} to retrieve the final status and failure details.


Limit errors

internalStatusHTTPDescriptionAction
BLOCKED_UIF400The operation exceeds the user's available limit; fund-origin documentation is neededTrigger the raise-limits flow
LIMIT_NF404No limit record found for the userVerify the user ID; contact support if it persists

Transfers do not fail this way. A POST /wallet/v1/transfers over the Virtual Accounts limit is still accepted (2xx) and fails later with R3 — see Compliance rejection codes above.


Compliance errors

internalStatusHTTPDescriptionAction
IS_IN_LISTS400User matched a compliance restriction listHard block, not user-recoverable; contact support
IS_FACTA400User is a US National (FATCA)Hard block, not user-recoverable; contact support
IS_DEAD400The legal ID belongs to a deceased personHard block, not user-recoverable; contact support
IS_UNDER_AGE400The legal ID belongs to a person under 18 years oldHard block, not user-recoverable; contact support
USER_BLOCKED409User is blockedDo not retry; resolve the block
USER_BLOCKED_FUNDS409User has blocked fundsDo not retry; contact support
USER_NEEDS_EXTRA_DOC409Extra documentation was requested for this userUpload the requested documentation

See User blocks and restrictions for what each block means and how it is lifted.


Recovery strategy

PhaseAction
Account creation failedCheck user onboarding status; retry after resolving
Insufficient fundsTop up account balance and retry
Duplicate transfer (409)Fetch existing transfer instead of creating
Limit exceeded (BLOCKED_UIF)Trigger the raise-limits flow (FUNDS document)
Compliance block (409)Do not retry; contact support with the user's legalId
Transient failure (5xx)Retry with exponential backoff

Did this page help you?