Error Codes
Every error the v1.1 APIs can return, what causes it, and what to do next. Includes the authentication, validation and retry behaviour you need to handle before going live.
This page lists the errors you can receive from the v1.1 APIs and what to do about each one. It covers the gateway layer that every request passes through, the validation layer, and the business rules of each API.
Blocked right now? Check these five things first
- Login returns
401 Invalid API Key.POST https://api-company-<env>.vertofx.com/users/loginonly accepts the encryptedapiKeydescribed in Certificate-Based Authentication: your API key and a millisecond timestamp, RSA-encrypted with your certificate. A plain API key is always rejected. The timestamp must be within 30 seconds of our server time, so check your server clock.- Every call returns
401 Unauthorized. SendAuthorization: Bearer <jwt>, withBearercapitalised and one space. Tokens expire after 60 minutes and there is no refresh token, so log in again.- You get
403 Access Denied: You are not allowed to perform this action.This is usually not a token problem. Check the host, the path, the HTTP method, your user's role permissions, and that onboarding (KYB) is complete. See 403 Access Denied.- You get
400with anerrorsarray. Your request does not match the API schema. Readerrors[].pathanderrors[].message. See Validation errors.- A payment or trade timed out, or returned
5xx. Do not resend it blindly. Look it up first. See Retries and duplicates.
How to read an error
Always branch on the HTTP status code first. The code field in the body, when present, is the same number as the HTTP status. It is not a separate error code.
Error bodies come in these shapes:
| Shape | Example | Where you see it |
|---|---|---|
| Standard | {"code": 400, "message": "Wallet label must be unique"} | Most business errors on all APIs. |
| Validation | {"errors": [{"path": "/body/currency", "message": "must be equal to one of the allowed values", "errorCode": "enum.openapi.validation"}], "message": "request/body/currency must be equal to one of the allowed values", "success": false} | Requests that don't match the API schema. Always HTTP 400. Exchange responses also include "code": 400. Beneficiary returns the standard shape instead (see Validation errors). |
| Exchange coded | {"success": false, "code": 409, "errorCode": "ER_EN_0001", "message": "..."} | Some FX trade errors. See FX under Errors by API. |
Problem details (application/problem+json) | {"type": "https://docs.vertofx.com/errors/submission-blocked", "title": "Submission blocked", "detail": "...", "status": 422} | Onboarding submission checks and submit only. |
| Message only | {"message": "Endpoint request timed out"} | Platform timeouts, platform-wide throttling and some wallet account provisioning errors. |
| Field error | {"error": "Bad Request", "message": "Wallet does not exist"} | GET /wallets/{walletId}/fetch-statements only. |
Recommended handling:
- Branch on the HTTP status.
- If the body has
errorCode(exchange) or a problem-detailstype(onboarding), branch on that. These values are stable. - If the body has an
errorsarray, useerrors[].errorCodeanderrors[].pathto find the field to fix. - Otherwise treat
messageas human-readable text for logs and support. Messages can change, so don't build logic that matches them exactly.
Tracing a request
| Header | Direction | Use |
|---|---|---|
vfx-correlation-id | Request (optional) | Send your own unique ID per logical operation. It is echoed back on the response. If you don't send one, we generate one. |
vfx-api-call-id | Response | Our ID for the request. Include it when contacting support. Not present on gateway-level errors (401, 403, 404, 429, 502, 504) or on malformed-JSON errors. |
x-amzn-requestid | Response | Present on every response, including gateway errors. Include it when vfx-api-call-id is missing. |
Errors from the platform layer (all APIs)
Every request passes through the API gateway, a network security layer and the authorizer before it reaches the API itself. These errors look the same on every host.
| HTTP | Body | Cause | What to do |
|---|---|---|---|
| 401 | {"code": 401, "message": "Unauthorized"} | Missing, malformed or expired token, a token from another environment, a token revoked after a password reset, or a temporary platform issue. | Log in again and retry once. If it persists, contact support. Don't loop on re-login (see the note on maintenance below). |
| 403 | {"code": 403, "message": "Access Denied: You are not allowed to perform this action."} | Several causes. See 403 Access Denied. | Don't retry unchanged. |
| 403 | {"code": 403, "message": "This operation is temporarily restricted due to recent password change."} | A sensitive action (payments, FX trades, recipients, API keys, sub-accounts) shortly after the password of the user that owns your API key was changed. | Wait and retry later. |
| 403 | {"code": 403, "message": "Request blocked"} | The request was blocked by our network security layer. On the beneficiary host the message is We are currently experiencing a technical issue on our end. Please try again in a few minutes. | Check the request body for unusual content. Contact support with x-amzn-requestid. |
| 405 | A non-JSON (HTML) body with header x-amzn-waf-action: captcha | The request was challenged by our network security layer. Seen on POST /users/login when the body is not valid JSON. | Don't parse the body. Send valid JSON with Content-Type: application/json. If it persists, contact support with x-amzn-requestid. |
| 404 | {"code": 404, "message": "Endpoint not found or unsupported method"} | The path doesn't exist at the gateway, for example the host root /. | Check the URL. Note that with a valid token, an unknown path usually returns 403, not 404. |
| 429 | {"code": 429, "message": "Too many calls. Further attempts would also count as calls and would delay the cooldown. Contact support to request for a higher limit."} | Your company's rate limit. The default is 1,000 calls per 5 minutes per company, shared by all APIs and by every other login of your company, including dashboard users. API-key logins also have a per-second limit. | Stop sending, back off and retry later. Every attempt counts towards the limit. No Retry-After header is sent. Contact support to raise the limit. A changed limit applies to tokens issued after the change. |
| 429 | {"message": "Too Many Requests"} | Platform-wide burst protection on that API. | Retry with exponential backoff and jitter. |
| 400 | {"errors": [], "message": "request entity too large", "success": false} | Request body over the size limit: 100 KB on most APIs. On Payments and Onboarding, keep request bodies under 5 MB: larger ones fail before they reach the API, with a 5xx or the 413 below. Beneficiary returns 413 with {"code": 413, "message": "request entity too large"}. | Reduce the payload. Upload files to the signed upload link, not in the JSON body. |
| 413 | {"message": "Request Too Long"} | Body over 10 MB at the gateway. | As above. |
| 502 | {"message": "Internal server error"} | The API failed before it could respond. | Treat the outcome as unknown. See Retries and duplicates. |
| 504 | {"message": "Endpoint request timed out"} | The request took longer than 29 seconds. The request may still complete after you receive the 504. | Don't resend write requests. Look up the result first. See Retries and duplicates. |
| 503 | {"message": "Verto platform is down for maintenance."} | Planned maintenance. Returned by login and some onboarding routes. During maintenance, authenticated calls return 401. | Wait and retry later. If you re-login automatically on 401, stop retrying when login returns 503. |
403 Access Denied
Access Denied: You are not allowed to perform this action. is returned for all of these causes:
- The path, HTTP method or path casing is wrong. With a valid token, a typo returns 403, not 404.
- You called an endpoint on the wrong host. For example, a wallet path sent to
api-payment-<env>.vertofx.com. Each API has its own host. - A path parameter contains characters other than letters, digits,
_and-. - Your user's role lacks the permission for this endpoint. Check the role of the user that owns your API key in the Verto dashboard.
- Your company (or the sub-account you're acting as) hasn't completed onboarding (KYB). Company and onboarding endpoints still work.
- You're acting as a sub-account whose link isn't
ACCEPTEDyet. After it's accepted, it can take up to 5 minutes before calls stop returning 403. - Your account tier doesn't include this endpoint.
Re-logging in does not fix a 403. Only a 401 means your token is the problem.
Validation errors
Each API checks requests against its published schema before running any business logic. A mismatch returns 400:
{
"errors": [
{
"path": "/body/sourceAmount",
"message": "must be >= 0.01",
"errorCode": "minimum.openapi.validation"
}
],
"message": "request/body/sourceAmount must be >= 0.01",
"success": false
}errors[].errorCode is <rule>.openapi.validation. The rules you will see:
errorCode | Meaning |
|---|---|
required.openapi.validation | A required field or query parameter is missing. |
type.openapi.validation | Wrong JSON type, for example "100" where a number is expected, or 123 where a string is expected. |
enum.openapi.validation | Value not in the allowed list. Enums are case-sensitive: usd and apikey are rejected. |
format.openapi.validation | Wrong format. For date-time fields, the message is Please specify date in ISO format, e.g. 2025-01-01T00:00:00Z. A plain date such as 2025-01-01 is rejected. |
pattern.openapi.validation | The value doesn't match the required pattern. |
minimum / maximum / minLength / maxLength / minItems / maxItems .openapi.validation | Outside the allowed range or length. |
oneOf.openapi.validation / anyOf.openapi.validation | The body doesn't match any allowed variant. These requests also list the errors for every variant, so look for the error on the field you meant to send. |
readOnly.openapi.validation | You sent a field that can't be set. Remove it. |
additionalProperties.openapi.validation | You sent a field that isn't allowed (onboarding submit only). |
Errors with no errorCode:
| Message | Cause |
|---|---|
Unknown query parameter '<name>' | Every API rejects query parameters it doesn't define. Remove extra parameters, including cache-busters. |
Empty value found for query parameter '<name>' | You sent ?name= with no value. Omit the parameter instead. |
not found / <METHOD> method not allowed | Wrong path or method. Usually you'll see 403 first. |
unsupported media type <type> / media type not specified | Send Content-Type: application/json. |
A JSON parse message, for example Unexpected token } in JSON at position 10, with "errors": [] | The body isn't valid JSON. |
Beneficiary API: validation errors are returned as
{"code": 400, "message": "body must have required property 'paymentMode'"}, with noerrorsarray. Wrong methods return405, unknown paths404, and a wrong content type returns415, rather than 400.
What to do for each status
| HTTP | Retry? | Action |
|---|---|---|
| 400 | No | Fix the request. Business-rule messages are listed in the API sections below. |
| 401 | Once, after logging in again | See platform errors. |
| 403 | No | Permission, onboarding, tier, sub-account status or wrong path. See 403 Access Denied. |
| 404 | No | Check the ID and that it belongs to your company or sub-account. |
| 409 | No, unless the message says to try again | Conflict: duplicate, or an operation already in progress. Read the message. |
| 422 | No | Onboarding submission blocked, or an IBAN that couldn't be verified. Fix the data. |
| 429 | Yes, with backoff | See platform errors. |
| 500 / 502 / 504 | Reads: yes. Writes: only after checking | A write may have succeeded. Follow Retries and duplicates. |
Retries and duplicates
The
Idempotency-Keyheader is not supported on payments, FX trades, transfers, wallets or recipients. It is ignored there. The only endpoint that reads it is onboardingPOST /companies/{companyId}/onboarding-data/submit.
Duplicate protection on money-moving endpoints comes from an ID in the request body:
| Endpoint | Body field | Behaviour |
|---|---|---|
POST /payments/create | paymentId | A repeat of the same paymentId within 60 seconds returns 400 This payment request has already been submitted. .... This also applies when the first attempt failed validation, so wait 60 seconds or use a new ID after fixing the request. After a payment exists, any reuse returns 400 Duplicate Payment ID(<id>) found. paymentId must be unique across the whole platform, so use a UUID. Without a paymentId there is no duplicate protection. |
POST /fx/payments | paymentId | Required for API-key logins. A repeat within 60 seconds returns 400 This payment request has already been submitted. .... If an order already exists for that paymentId, the same message is returned with errorCode: "ER_EN_0006". Once an order is created, the paymentId can't be reused even if a later step failed. Use a new UUID per attempt. |
POST /transfer | externalUniqueRef | Max 40 characters. Reuse returns 400 externalUniqueRef already exists. Please verify your input.. While a transfer with that reference is in progress, or if its outcome was unknown, reuse returns 400 A transfer with this externalUniqueRef is already being processed. ... for up to 7 days. Must be unique across the platform. |
POST /sub-accounts | externalId | Reuse within your company returns 409 externalId already exists for this company. Send an externalId so that retries can't create duplicate sub-accounts. |
POST /recipients, POST /{companyId}/wallets | none | Not idempotent. A retry creates a second recipient or wallet. Before retrying, list recipients or wallets to check whether the first call succeeded. |
When a write times out (504), returns 5xx, or the connection drops:
- Don't send the same request with a new ID.
- Look the operation up:
- Payment:
GET /payments/{paymentId}(with thepaymentIdyou sent, not theTO-reference). - FX trade:
GET /fx/{paymentId}orGET /fx/{reference}. - Transfer, recipient or wallet: list and look for your record.
- Payment:
- Process webhooks. They are the source of truth for final payment and FX states.
- Only if the lookup confirms nothing was created, retry with a new ID. For payments and FX trades, wait 60 seconds first or use a new ID.
Errors by API
Open a section to see every error for that API. Each row shows the HTTP status, the exact message you receive, and what to do about it.
Body: {"mode": "apiKey", "clientId": "...", "apiKey": "<encrypted>"}. Success returns 200 with userId, companyId and jwt. The token is in jwt and is valid for 3,600 seconds.
mode is missing or isn't apiKey. It's case-sensitive: send "mode": "apiKey". An unknown value such as APIKEY returns a validation error (enum.openapi.validation) instead.
apiKey is empty.
Unknown clientId. Sandbox and production credentials are different; check you're using the right one.
Returned for any of: a plain (unencrypted) key, the wrong certificate, a timestamp more than 30 seconds from server time, a wrong key, an inactive or revoked key, or no certificate on the account. Encrypt apiKey:timestampMs exactly as in Certificate-Based Authentication, generate it immediately before the call, and sync your server clock (NTP). If it still fails, check the key's status in the Verto dashboard.
Your API key has an IP allow-list and the calling IP isn't on it. Add your server's public egress IP to the key.
The user or company is blocked. Contact support.
Locked by Verto. Contact support.
Security restriction. Contact support.
The company is archived or its onboarding was rejected. Contact support.
The user profile or onboarding record is missing. Contact support.
Also returned when clientId is missing from the body. Send clientId.
Planned maintenance. Retry later.
Acting as a sub-account. There is no header for this. Call POST /sub-accounts/{subCompanyId}/login with your token and use the jwt it returns for the sub-account's calls. Until the sub-account link is ACCEPTED and its onboarding is approved, that token works on company and onboarding APIs but returns 403 Access Denied on wallet, FX, beneficiary and payment APIs.
POST /sub-accounts/{subCompanyId}/login
Note the different body shape. Your role lacks the Sub-Accounts write permission.
The ID isn't a sub-account of your company.
This sub-account isn't available for login, for example because its link was rejected or it's dormant.
The sub-account is archived. Any other login 403 from the Authentication section can also appear here, because those checks run against your (the parent's) user and company.
POST /sub-accounts
Success is 201.
country must be the exact English country name from the list, such as United Kingdom. ISO codes like GB are rejected.
externalId must be 1–50 characters: letters, digits and - only.
You sent country: null.
subCategory must exactly match a Verto industry name.
Your own onboarding isn't approved yet.
Your account isn't enabled for that accountType. Contact your account manager.
Your super-admin role lacks the Sub-Accounts permission.
Duplicate externalId. Look up the existing sub-account instead of creating another.
The sub-account may have been created anyway. List sub-accounts by externalIds before retrying.
POST /sub-accounts/list
limit (1–100) and skip are required query parameters. When you send searchText, the status filter is ignored.
POST /sub-accounts/{subCompanyId}/tnc/send-email
Queued for sending. Send it only when the sub-account's onboarding is approved and its director hasn't accepted the T&C yet (in POST /sub-accounts/list: companyStatus APPROVED and linkedStatus PENDING, PENDING_POA or PENDING_ACCEPTANCE_BY_CHILD). The link is valid for 14 days, and earlier links are invalidated. Always send a valid email: it isn't validated, and the email goes to the address you send.
The shareholder isn't an active, approved director of the sub-account.
Currently also returned when the sub-account doesn't exist. Check the subCompanyId.
GET and POST /companies/{companyId}/onboarding-data
You sent a read-only field such as company.country, company.email or shareholder kycStatus. Sending null also fails. Remove the field.
companyId isn't your company or one of your sub-accounts. Also returned for a companyId that doesn't exist.
Your role lacks the Sub-Accounts permission for this sub-account.
Or ... has been rejected. ... The application has been decided. Document-only updates are still accepted.
Or Document with id <id> not found. Wrong ID on UPDATE, DELETE or ARCHIVE.
Or ... with email <email> is already present. Duplicate shareholder.
A document DELETE needs a non-empty reason. The errors list also contains errors for the other actions; look for the one whose path ends in /reason (required.openapi.validation if it's missing, minLength.openapi.validation if it's empty).
Also Answer should be a list of available options for a multiselect question., Answer should be a string for a dropdown question. and Invalid answer provided. Use the question IDs and options returned by the API.
Saving data never submits the application. company.telephone and company.countryCode are ignored without an error. company.email and company.reference are read-only: sending them returns 400 readOnly.openapi.validation, so remove them before saving. Max 5 shareholders and 5 documents per call, and max 2 addresses. Verto assigns document ids. An id sent on ADD is ignored, so a retried ADD creates a second document. Before retrying, check the documents returned by GET onboarding-data.
GET /companies/{companyId}/onboarding-data/checks
Only for KYC level 3 sub-accounts: a normal account gets 404 submit-api-not-available, and a KYC level 0 sub-account gets 409 submission-not-required. Returns 200 with an issues list. Each issue has code, severity (BLOCKING or WARNING), tier, resource, resourceId, field and message. Only BLOCKING issues stop submission, so decide on severity, not on code: the same code can also come as a WARNING.
BLOCKING codes: FIELD_MISSING, FIELD_INVALID, DOCUMENT_MISSING, OWNER_REQUIRED, SIGNATORY_REQUIRED, DIRECTOR_REQUIRED, COUNTRY_NOT_SUPPORTED, DOCUMENT_CLASSIFYING (a document is still being read; check again shortly), CHECKS_IN_PROGRESS (background checks are still running; check again shortly), CHECKS_FAILED (background checks couldn't finish; save the onboarding data again to re-run them) and VERIFICATION_FAILED (part of the application couldn't be verified; field says which part and message says why). Warning-only: VERIFICATION_PENDING and review findings such as DOCUMENT_EXPIRED and DATA_MISMATCH. New codes may be added, so treat any unknown BLOCKING code as blocking.
POST /companies/{companyId}/onboarding-data/submit
Errors are problem details. Branch on the end of the type URL.
Submit is only available for sub-accounts.
KYC level 0 sub-accounts are approved automatically.
Already submitted and awaiting review.
The application is in a stage that can't be submitted.
Another submit for this company is running. Wait, then check its status.
The account is already at the requested tier.
Blocking issues remain (see the checks endpoint), or the requested tier is below what the selected products need.
30 calls per 5 minutes per company.
Send an Idempotency-Key header. Resending the same key as your last successful submit returns the original response. Failures aren't replayed.
POST /documents/generate-upload-link
Default list: jpeg, jpg, pdf, png, svg.
Unknown documentTypeId.
30 links per 5 minutes per company. Every call counts.
Links aren't tied to a company, but the rate limit counts against the company in your token. If you upload for many sub-accounts, request links with each sub-account's token. Links expire after at most 10 minutes.
POST /{companyId}/wallets
Create a wallet. Success is 200 with the wallet object. Body: currency (required, uppercase ISO code), type (required, standard or fx_balance), customReferenceLabel (optional, max 75 characters).
Not idempotent. You can hold more than one wallet in the same currency, so a retried create makes a second wallet. Before retrying, list wallets to check whether the first call succeeded. Account details (IBAN or account number) aren't created with the wallet; see funding methods below.
currency must be an uppercase ISO code (usd is rejected); type must be standard or fx_balance; both are required.
customReferenceLabel is longer than 75 characters.
Wallets aren't available for this currency.
customReferenceLabel exactly matches (case-sensitive) the label of an active wallet in the same currency. Use a different label.
You sent type: fx_balance. Send standard.
companyId is a sub-account whose link isn't ACCEPTED yet.
companyId isn't yours or one of your sub-accounts, or an unexpected failure. Check the companyId; if it's correct, list wallets before retrying.
GET /{companyId}/wallets
List wallets. limit (max 300) and skip are required. Optional filters: currency, type (standard, fx_balance), isDefault, isArchived, walletIds, searchTerm. Returns 200 with {"totalCount": 0, "items": []} when there are no wallets.
limit or skip missing, limit over 300, or a filter value outside its allowed list.
Remove parameters the endpoint doesn't define.
companyId isn't yours or one of your sub-accounts.
companyId is a sub-account whose link isn't ACCEPTED yet.
Temporary failure. Retry with backoff.
GET /{companyId}/wallets/{walletId}
Get one wallet. Success is 200 with the wallet object.
Unknown walletId. This is a 400, not a 404.
The wallet belongs to a different companyId than the one in the path.
companyId isn't yours or one of your sub-accounts.
companyId is a sub-account whose link isn't ACCEPTED yet.
Temporary failure. Retry with backoff.
GET /{companyId}/wallets/{walletId}/fundingMethods
Get the wallet's account details. Optional query parameters: autoCreate (boolean), partnerProduct, accountName (parent, sub). Success is 200 with totalCount, items and metadata (isEligibleForSegregatedLocalAccount, isEligibleForSegregatedGlobalAccount).
Unknown walletId. This is a 400, not a 404.
The wallet belongs to a different companyId than the one in the path.
Default wallet only. Complete the company sub-category in onboarding.
companyId isn't yours or one of your sub-accounts.
companyId is a sub-account whose link isn't ACCEPTED yet.
Temporary failure. Retry with backoff.
Account provisioning: GET .../fundingMethods?autoCreate=true
Account details are created during this call. Errors are only returned if the wallet had no accounts yet; otherwise you get 200 with the existing accounts. No webhook is sent when account details are created, and for some currencies the account number appears a short time later, so call GET .../fundingMethods again (without autoCreate) to see it.
FX balance wallets can't have account details.
Your account isn't eligible yet. Contact your account manager.
No account provider for this currency on your account.
Your onboarding data couldn't be found. Contact support.
Also Provider <name> already linked with <local|global|stablecoin> account for this wallet, Wallet already linked to IBAN Account. and Cannot link to wallet. Already provisioned: call without autoCreate.
Error from the account provider, passed through with its status and no code field.
Returned when no provider detail is available. The account may still have been created: call without autoCreate before retrying.
POST /statement/export
Request a statement file. Success is 202 {"message": "The request is accepted and response will be delivered by webhook"}; the file is delivered by the Statement generated webhook (and emailed if you sent email).
- Query:
since,till(date-time, e.g.2025-01-01T00:00:00Z),format(csvorpdf, defaultcsv).sinceandtillare optional in the schema, but always send both. - Body:
walletIds(required, array of numbers, not strings),email(optional, an active Verto user of your company). - Wallets are checked against your token's company. For a sub-account's wallets, use the sub-account's token.
since and till must be full date-times. Message: Please specify date in ISO format, e.g. 2025-01-01T00:00:00Z.
walletIds must be numbers; format must be csv or pdf.
walletIds is empty.
The wallet doesn't exist or isn't in your token's company. Also returned (with no ids listed) if the same id is sent twice.
Compared by UTC date: a later time today is accepted.
email is blank. Omit it or send a real address.
email must belong to an active user of your company.
The token isn't a company user's token.
Temporary. Retry.
Also returned when walletIds is missing from the body. Send walletIds; otherwise retry.
GET /wallets/{walletId}/fetch-statements
List a wallet's transactions. Required query parameters: limit (1–100), skip (0 or more), since, till (date-time). Optional searchTerm (max 50 characters); when it's sent, the date range is ignored (since and till are still required). Success is 200 {"totalCount": n, "items": [...]}.
Errors on this endpoint use the field-error shape {"error": "...", "message": "..."}, except the last row.
A required parameter is missing, limit is over 100, a date isn't a full date-time, or searchTerm is over 50 characters.
limit is 0 or negative.
skip is negative.
Unknown wallet.
The wallet isn't in your token's company. Sub-account wallets need the sub-account's token; the parent's token is refused.
Temporary failure. Retry.
Errors use {"code": <status>, "message": "..."}. IBAN errors also include a stable errorCode and details.
POST /recipients and PUT /recipients/{recipientId}
Create returns 200. PUT re-validates the whole recipient, so send the full set of bank and name details, not only the fields you're changing. Creating the same account twice creates two recipients; check GET /recipients?accountNumbers=... before retrying.
Or The currency id <id> is not supported. Unknown currency.
Or Currency <name> is no longer available. The currency isn't available for recipients.
Or Payment in <CUR> not supported. Use a supported paymentMode for the currency.
Also Bank code is required, Bank name is required and Bank address country code is required.
Failed IBAN checksum (any corridor).
One of the corridor-specific format rules for the currency and payment mode. Others include Bank Code / BSB Code of 6 digits is required, ABA Code/Routing Number should be 9 characters, IFSC Code should be 11 characters and SWIFT code should be between 8 to 11 characters.
Characters 5–6 of the SWIFT/BIC are the bank's country, and that country is on Verto's restricted (sanctioned) list. We can't pay this bank. Use a bank in a different country.
Or Beneficiary country code is mandatory for international payment mode. INTERNATIONAL requires beneficiaryAddress.
Address fields allow letters, digits and spaces (and commas in the beneficiary address), max 35 characters.
Same rule for Last Name and Company Name.
Or Recipient email is required for <CUR> currency. INR and KRW local payments.
Or Incorrect Bank details. The bank details couldn't be verified.
You sent the stablecoin paymentMode, but stablecoin recipients aren't enabled for your company. Contact your account manager.
PUT on a deleted recipient.
PUT on an unknown recipient.
Stablecoin wallet detail errors currently return 500 with a descriptive message like this one. Fix the request as the message says.
A new recipient is either approved or pending, depending on your account settings. Payments to a recipient that isn't approved fail with 400 The beneficiary account has not been approved yet. ... Listen for the beneficiary status webhook.
IBAN errors (EUR, BRL and SAR international)
The IBAN is checked against bankAddress.countryCode, so set it to the bank's country.
The IBAN doesn't start with the country code of bankAddress.countryCode. Either the IBAN is wrong or countryCode isn't the bank's country. details shows the prefix you sent and the one expected.
The IBAN has the wrong number of characters for that country. Spaces are removed before counting. details shows the length you sent and the length expected.
The prefix and length are fine, but either the checksum fails (usually a typo) or our bank-data provider can't find a bank for this IBAN. Check the IBAN with the recipient. Don't retry it unchanged.
GET /recipients/{recipientId}
Deleted recipients are still returned, with isArchived: true.
The IBAN doesn't start with the country code of bankAddress.countryCode. Either the IBAN is wrong or countryCode isn't the bank's country. details shows the prefix you sent and the one expected.
The recipient belongs to another company, or it isn't tied to any company. Use a recipient ID from your own GET /recipients. For a sub-account's recipients, use the sub-account's token.
GET /recipients
Always send limit (max 100). Unknown query parameters are rejected.
DELETE /recipients/{recipientId}
Deleting an already deleted recipient returns 200.
Unknown recipient. This is a 400, not a 404.
POST /uploadDocuments
Links expire after 15 minutes.
The extension after the last . isn't in the list, or the file has no extension. The check ignores case. It applies to every file in the array, and if one file fails, the whole request is rejected.
A file in the array has a missing, empty or non-string fileName.
The companyId query parameter doesn't match the company in your token. Drop companyId, or use the token of the company you're uploading for.
POST /confirm-payee
UK requests must use "type": "UK", with name, accountType (PERSONAL or BUSINESS), a 6-digit sortCode with no dashes, and accountNumber. Nigeria requests use bankCountry: "NG", bankCode and accountNumber. Don't mix the two shapes. The result (match, close match, no match) is in the 200 body (status.identifier and detailedStatusIdentifier); it's never an HTTP error.
The token isn't a client user token.
The verification provider is unavailable, or no account was found. Treat it as "could not verify".
Access checks
Applies to quote, bulk rate, trade and set-markup. Note the body shape.
API access isn't enabled for your account, or the login mode isn't supported.
The calling IP isn't on your API key's allow-list.
POST /fx/quote
The quote's vfx_token expires at expiry. The validity window depends on your plan and the currencies, and can be as short as 30 seconds. Request a new quote for each trade, immediately before booking it.
Must send correct request payload
Value of the amountCurrency should match either amountFrom or amountTo
Or Invalid currencyTo: <X>. The currency isn't available.
Must send correct request payload
Must send correct request payload
The currency has no decimals.
Must send correct request payload
paymentMode: later isn't enabled for your account.
The pair or amount can't be priced right now.
Pricing is temporarily unavailable. Retry with backoff.
POST /fx/bulk-rate
Returns indicative rates only (no vfx_token), so you can't trade on them. If exchangeRateRes is missing from a 200 response, the rates were unavailable; retry.
POST /fx/payments
vfxToken has expired or isn't a valid token. Get a new quote.
Get a new quote.
Duplicate paymentId. Sometimes includes errorCode: "ER_EN_0006". See Retries and duplicates.
API-key logins must send paymentId.
The quote's currency pair doesn't match the source and target wallets (or beneficiary), or an amount has decimals for a whole-number currency.
Or The target wallet could not be found. ... Wrong wallet ID, or the target is the same as a source.
Unknown targetAccountId.
sources don't add up to sourceAmount.
Or Minimum transaction amount for <country>[<CCY>] is <min>. Checked on the source amount.
customPaymentReference allows letters, digits, spaces and -, under 100 characters.
Or Supporting documentation is required for this third-party payout amount. ... Account tier limits. Send the document key in supportingDocS3Key.
Or Wallet withdrawals are currently disabled for the organisation. ... Restricted on your account. Contact support.
Onboarding isn't approved.
Your role lacks FX trade permission.
Includes insufficient balance. Check the wallet balance, then look up the trade before retrying.
Outcome unknown, and the trade may exist. The same applies to other 500s. Look it up with GET /fx/{paymentId} before retrying.
For payouts, always send sourceWalletId or sources. Omitting both currently returns 500.
GET /fx/{reference}
A trade can take a few seconds to appear after creation. If you get a 404 immediately after a successful create, retry after a short delay.
POST /fx/list
limit and skip are required query parameters.
GET and POST /fx/markup/config
limit and skip are required on GET. markupPerc must be 0–10.
currency_pair needs both currencyFrom and currencyTo.
POST /payments/create
Success is 201. A 201 response with {} means a recurring schedule was created (recurFrequency WEEKLY or MONTHLY), not a payment. Without a scheduledDate, nothing is scheduled even though you get 201 {}.
Validation errors are listed for every payment type, so look for the error on the paymentType you sent. IDs (sourceWalletId, targetAccountId, purposeId, ...) must be strings containing digits, for example "123".
Or Duplicate Payment ID(<id>) found. See Retries and duplicates.
Also Target account ID is required for wallet payout payments and Please provide a Purpose ID for your wallet payout payment. ... A missing or non-numeric ID. For WALLET_PAYOUT, send sourceWalletId, sourceAmount, targetAccountId and purposeId.
sourceAmount is missing, 0 or negative. Send a positive amount.
Your role lacks the payment permission for this paymentType.
The source wallet doesn't exist or isn't yours (WALLET_PAYOUT).
No recipient was found for targetAccountId, either because it was deleted or because the ID is wrong.
The recipient is pending or rejected.
The wallet currency must equal the recipient currency. For cross-currency payouts use POST /fx/payments.
customPaymentReference for WALLET_PAYOUT allows letters, digits and spaces only, max 35 characters.
Insufficient funds (WALLET_PAYOUT).
scheduledDate is in the past.
Also Supporting documentation is required for this third-party payout amount. ... and Unable to verify tier limits for this currency at this time. ... Account tier limits.
Also Wallet withdrawals are currently disabled for your organisation. ... and Stablecoin withdrawals are currently disabled for your organisation. ... Restricted on your account. These don't reserve the paymentId.
Your company's status is inactive, blocked, deleted or frozen. Contact support. Don't retry.
sourceWalletId is an fx_balance wallet. Pay from a standard wallet.
Or Your wallet is currently disabled and cannot be used. ...
WALLET_TO_BUSINESS.
The receiving business hasn't completed onboarding.
Or Recipient is not set up to receive wallet-to-wallet transfers. Please use a different payment method. WALLET_TO_BUSINESS.
Or Wallet currencies are not same, make convertWithinWallets request for FX. TRANSFER_WITHIN_WALLETS. For different currencies use POST /fx/payments.
WALLET_TO_BUSINESS and TRANSFER_WITHIN_WALLETS currently return insufficient balance as a 500. Check the balance, then look up the payment before retrying.
Outcome unknown. The same applies to other 500s. Look up GET /payments/{paymentId} before retrying.
GET /payments/{paymentId}
Use the paymentId you sent, not the TO- reference. Don't add query parameters.
Not found, or another company's payment. The body is a JSON string, not an object.
GET /payments/payment-tracking/{reference}
reference must be uppercase TO-... or EN-...
Unknown reference, or not your payment.
The body is a JSON string. Tracking isn't available yet; retry later.
Temporary failure. Retry.
GET /payments/purpose-codes
currency and type (LOCAL or GLOBAL) are required query parameters. Add purpose=true to get payment purpose codes.
POST /transfer
Success is 200. amount, sourceWalletId and targetWalletId are numbers here, unlike /payments/create. All errors are returned as 400.
Use a shorter reference. Leading and trailing spaces are trimmed first. A UUID (36 characters) fits.
A transfer with this reference already exists. The check covers the whole platform, not just your company. If you're retrying, the original transfer probably went through, so look it up and don't resend. If this really is a new transfer, use a new reference.
sourceWalletId and targetWalletId are the same. Send two different wallets.
amount is 0 after rounding to 2 decimal places (for example, 0.004). Send at least 0.01.
The source wallet isn't yours or your sub-account's.
The source wallet's available balance is less than amount. Nothing was debited. Fund the wallet, then retry.
The source wallet wasn't found, or currency doesn't match the source wallet's currency. Check both.
POST /documents/generate-upload-link
Links expire after 10 minutes.
fileName is missing or empty.
fileName contains /, \ or .. anywhere in it. That includes ordinary names like Invoice..pdf. Rename the file.
The file extension isn't one of these, or there's no extension. The check ignores case.
The documentInfo.reference you sent isn't a TO-…/EN-… reference, doesn't exist, or belongs to another company. reference is optional when you generate the link.
Contacting support
Send us:
- the
vfx-api-call-idresponse header, orx-amzn-requestidif it's missing; - your
vfx-correlation-id,paymentIdorexternalUniqueRef; - the environment (sandbox or production), host, method and path;
- the HTTP status and full response body;
- the UTC time of the request.
Updated 3 days ago

