Errors
Three errors account for nearly every push that never reaches a payout network. All are integration-time problems rather than declines, so do not map any of them to a customer-facing decline message.
VE_001 — the payload does not satisfy the schema
{
"code": "VE_001",
"message": "Validation error",
"errors": [
{
"field": "recipient.paymentMethod.bankCode",
"message": "recipient.paymentMethod.bankCode does not match the expected regex ^[0-9]{3}$"
}
]
}
HTTP 400. The most common push failure, and the one the country coverage table exists to prevent.
The envelope key is code, not the errorCode that PAY_001 and PAY_271 carry. A client that reads only errorCode gets undefined on a validation failure — handle both.
errors[].field is a dotted path from the root of the request body, with an index where the value sits in an array (recipient.documents[0].document). errors[].message repeats that path and states the rule that broke.
errors lists the violations the gateway found, sorted by field path. Fix every entry and resubmit — and if another VE_001 comes back, work the new list the same way.
Message shapes
| Rule broken | Message | Example |
|---|---|---|
| Required field or object missing | <field> can't be empty | additionalData can't be empty |
| Array shorter than required | <field> must have at least N items but found M | recipient.documents must have at least 1 items but found 0 |
| Value outside the allowed set | <field> must be of one [A, B, C] | recipient.paymentMethod.accountType must be of one [CHECKING, SAVINGS, null] |
| Value fails the pattern | <field> does not match the expected regex <regex> | recipient.paymentMethod.bankCode does not match the expected regex ^[0-9]{3}$ |
| Value fails a named format | <field> does not match the expected format <format> | ipAddress does not match the expected format ipv4 |
| String too short or too long | <field> must have at least N characters | sender.firstName must have at least 1 characters |
| Number below the minimum | <field> must be a number greater than or equal N | amount.total must be a number greater than or equal 0 |
The enum and regex messages carry the accepted values and the pattern itself, so the response is usually enough to fix the payload without re-fetching the schema.
An explicit
nullcounts as an omission."bankCode": nullreturnsbankCode can't be empty, not a type error — nulls are stripped before the payload is validated. Anullinside amust be of one [...]list means the opposite: the field is optional, but constrained once you send it.
PAY_001 — no route for this country
{
"errorCode": "PAY_001",
"message": "No router found for agent and payment method"
}
HTTP 400. The gateway found no provider route that both belongs to your account and covers the destination country for the paymentMethod.type you asked for. It is raised when routing resolves an empty set — not when your payload is malformed.
Common causes, in the order worth checking:
| Cause | How to tell |
|---|---|
| The corridor is not enabled for your account | The same payload works in another country; GET /schema/{countryCode} returns a schema fine |
| No route for that payment method in that country | A BANK_DEPOSIT succeeds where a WALLET fails, or the reverse |
| Onboarding with the underlying provider is incomplete | Recently added corridor; the schema exists before the route does |
The schema endpoint is not a routing check. GET /schema/{countryCode} answers "what does this country require?", not "can I pay this country today?" — a country can return a valid schema and still yield PAY_001. Treat PAY_001 as a configuration issue to raise with your Inyo contact, not as something to retry.
PAY_271 — no schema for this country
{
"errorCode": "PAY_271",
"message": "Error retrieving JSON schema for country code: {countryCode}"
}
HTTP 400. Returned by GET /schema/{countryCode} when the code is not a supported payout country. Check the code is ISO 3166-1 alpha-3 (DEU, not DE) and appears in the country coverage table above.
What's Next
- Country coverage — What each corridor requires, so
VE_001never fires - Schemas — Read the rules straight from the source
- Response codes — Customer-facing decline categories