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/*.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
BAD_REQUEST | 400 | Validation failed on one or more fields | See the errors[] array for field details |
USER_NF | 404 | userAnyId not found | Verify the user ID |
USER_EXISTS | 409 | A user with that legal ID already exists | Idempotency check: fetch the existing user |
USER_EXISTS_EMAIL | 409 | A user with that email already exists | Use a different email or fetch the user |
PERSON_EXISTS | 409 | That legal ID is already declared under a different user in this company | Idempotency check: fetch the existing user by legalId |
Account creation errors
Applies to POST /wallet/v1/user-actions/assign-virtual-account.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
BAD_REQUEST | 400 | Validation failed on one or more fields | See the errors[] array for field details |
PERMISSIONS | 403 | Company is not enabled for Virtual Accounts in this user's country | Contact support to enable wallet clearance |
USER_STATUS | 409 | User is not active on the wallet platform | Verify user is fully onboarded and active |
UNKNOWN_USER | 409 | User has no legalId yet (identity declaration incomplete) | Complete identity declaration before requesting an account |
BANK_ACCOUNT_EXISTS | 409 | User already has a virtual account for this asset | Idempotency check: fetch the existing account for that asset |
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 |
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.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed corporate / shareholder fields | Fix request payload |
INVALID_SHAREHOLDERS | 400 | shareholders empty, or participationPercentage sum exceeds 100 | Ensure at least one shareholder and Σ ≤ 100 |
INVALID_REPRESENTATIVES | 400 | A 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 shareholder | Complete each representative, and send representedBy on every CNPJ shareholder when the company declares more than one representative |
CONFLICTING_EXTERNAL_ID | 400 | The same legalId (a person in more than one role) was given different externalId values | Use the same externalId — or none — for a person that appears as both a shareholder and a representative |
CANT_MODIFY_BENEFICIARIES | 409 | The company already has a persisted set of legal representatives, and this call tried to add, remove or swap one | Do 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.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
BAD_REQUEST | 400 | Validation failed on one or more fields | See the errors[] array for field details |
NO_FUNDS | 400 | Insufficient balance on the sender account | Check balance before submitting |
ACCOUNT_NOT_FOUND | 404 | Sender account not found | Verify account address |
INVALID_ACCOUNT | 404 | Sender account exists but has no usable address | Contact support |
TRANSFER_EXISTS | 409 | Transfer with same id already exists | Idempotency check: fetch existing transfer |
PAYMENT_DESTINATION_AMOUNT_MISMATCH | 400 | amount differs from the amount fixed by the QR code | Send the QR code's amount, as returned by GET /wallet/v1/address-info |
PAYMENT_DESTINATION_NOT_FOUND | 409 | The QR code was already paid or has expired | Do 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.
internalStatus | HTTP | Description | Action |
|---|---|---|---|
BAD_REQUEST | 400 | Validation failed on one or more fields | See the errors[] array for field details |
MASTER_VA_LOOP | 400 | The resolved virtual account is the company's own master account | Do not retry; verify the userAnyId |
USER_NF | 404 | userAnyId not found | Verify the user ID |
BANK_ACCOUNT_NF | 404 | User has no virtual account for the requested asset | Assign a virtual account for the asset first |
SYNTHETIC_EXISTS | 409 | A synthetic with the same idempotency key already exists | Idempotency 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 prefix | Category | Retry guidance |
|---|---|---|
E1 | Generic error | Potentially transient — safe to retry once |
P1–P3 | Payment rejected or expired | Potentially transient — retry-able |
C1–C10 | Destination account problems | Do not retry as-is; fix the destination key |
D1–D3 | Document (CPF/CNPJ) mismatch | Do not retry as-is; fix the recipient's legal ID |
U1–U2 | Recipient data (email, name) invalid | Do not retry as-is; fix the recipient data |
B1–B2 | Destination bank (min amount, invalid) | Adjust the amount or use another bank |
R1–R3 | Rejected by compliance | Do not retry as-is; see the compliance codes below |
Compliance rejection codes (R)
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).
| Code | Description | Action |
|---|---|---|
R1 | Rejected by compliance | Generic compliance rejection; contact support if it persists |
R2 | Breaks same name constraint | The counterparty's legal ID does not match the account owner's; use an account in the owner's name |
R3 | Exceeds virtual account limits | The 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
internalStatus | HTTP | Description | Action |
|---|---|---|---|
BLOCKED_UIF | 400 | The operation exceeds the user's available limit; fund-origin documentation is needed | Trigger the raise-limits flow |
LIMIT_NF | 404 | No limit record found for the user | Verify the user ID; contact support if it persists |
Transfers do not fail this way. A
POST /wallet/v1/transfersover the Virtual Accounts limit is still accepted (2xx) and fails later withR3— see Compliance rejection codes above.
Compliance errors
internalStatus | HTTP | Description | Action |
|---|---|---|---|
IS_IN_LISTS | 400 | User matched a compliance restriction list | Hard block, not user-recoverable; contact support |
IS_FACTA | 400 | User is a US National (FATCA) | Hard block, not user-recoverable; contact support |
IS_DEAD | 400 | The legal ID belongs to a deceased person | Hard block, not user-recoverable; contact support |
IS_UNDER_AGE | 400 | The legal ID belongs to a person under 18 years old | Hard block, not user-recoverable; contact support |
USER_BLOCKED | 409 | User is blocked | Do not retry; resolve the block |
USER_BLOCKED_FUNDS | 409 | User has blocked funds | Do not retry; contact support |
USER_NEEDS_EXTRA_DOC | 409 | Extra documentation was requested for this user | Upload the requested documentation |
See User blocks and restrictions for what each block means and how it is lifted.
Recovery strategy
| Phase | Action |
|---|---|
| Account creation failed | Check user onboarding status; retry after resolving |
| Insufficient funds | Top 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 |
Updated 12 days ago