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

  1. Login returns 401 Invalid API Key. POST https://api-company-<env>.vertofx.com/users/login only accepts the encrypted apiKey described 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.
  2. Every call returns 401 Unauthorized. Send Authorization: Bearer <jwt>, with Bearer capitalised and one space. Tokens expire after 60 minutes and there is no refresh token, so log in again.
  3. 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.
  4. You get 400 with an errors array. Your request does not match the API schema. Read errors[].path and errors[].message. See Validation errors.
  5. 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:

ShapeExampleWhere 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:

  1. Branch on the HTTP status.
  2. If the body has errorCode (exchange) or a problem-details type (onboarding), branch on that. These values are stable.
  3. If the body has an errors array, use errors[].errorCode and errors[].path to find the field to fix.
  4. Otherwise treat message as human-readable text for logs and support. Messages can change, so don't build logic that matches them exactly.

Tracing a request

HeaderDirectionUse
vfx-correlation-idRequest (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-idResponseOur 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-requestidResponsePresent 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.

HTTPBodyCauseWhat 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.
405A non-JSON (HTML) body with header x-amzn-waf-action: captchaThe 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 ACCEPTED yet. 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:

errorCodeMeaning
required.openapi.validationA required field or query parameter is missing.
type.openapi.validationWrong JSON type, for example "100" where a number is expected, or 123 where a string is expected.
enum.openapi.validationValue not in the allowed list. Enums are case-sensitive: usd and apikey are rejected.
format.openapi.validationWrong 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.validationThe value doesn't match the required pattern.
minimum / maximum / minLength / maxLength / minItems / maxItems .openapi.validationOutside the allowed range or length.
oneOf.openapi.validation / anyOf.openapi.validationThe 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.validationYou sent a field that can't be set. Remove it.
additionalProperties.openapi.validationYou sent a field that isn't allowed (onboarding submit only).

Errors with no errorCode:

MessageCause
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 allowedWrong path or method. Usually you'll see 403 first.
unsupported media type <type> / media type not specifiedSend 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 no errors array. Wrong methods return 405, unknown paths 404, and a wrong content type returns 415, rather than 400.


What to do for each status

HTTPRetry?Action
400NoFix the request. Business-rule messages are listed in the API sections below.
401Once, after logging in againSee platform errors.
403NoPermission, onboarding, tier, sub-account status or wrong path. See 403 Access Denied.
404NoCheck the ID and that it belongs to your company or sub-account.
409No, unless the message says to try againConflict: duplicate, or an operation already in progress. Read the message.
422NoOnboarding submission blocked, or an IBAN that couldn't be verified. Fix the data.
429Yes, with backoffSee platform errors.
500 / 502 / 504Reads: yes. Writes: only after checkingA write may have succeeded. Follow Retries and duplicates.

Retries and duplicates

🛑

The Idempotency-Key header is not supported on payments, FX trades, transfers, wallets or recipients. It is ignored there. The only endpoint that reads it is onboarding POST /companies/{companyId}/onboarding-data/submit.

Duplicate protection on money-moving endpoints comes from an ID in the request body:

EndpointBody fieldBehaviour
POST /payments/createpaymentIdA 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/paymentspaymentIdRequired 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 /transferexternalUniqueRefMax 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-accountsexternalIdReuse 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}/walletsnoneNot 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:

  1. Don't send the same request with a new ID.
  2. Look the operation up:
    • Payment: GET /payments/{paymentId} (with the paymentId you sent, not the TO- reference).
    • FX trade: GET /fx/{paymentId} or GET /fx/{reference}.
    • Transfer, recipient or wallet: list and look for your record.
  3. Process webhooks. They are the source of truth for final payment and FX states.
  4. 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.


Contacting support

Send us:

  • the vfx-api-call-id response header, or x-amzn-requestid if it's missing;
  • your vfx-correlation-id, paymentId or externalUniqueRef;
  • the environment (sandbox or production), host, method and path;
  • the HTTP status and full response body;
  • the UTC time of the request.

Did this page help you?