---
description: >-
  VE_001, PAY_001 and PAY_271 — the errors specific to building and routing a push,
  how to read a VE_001 validation response, and why none is a customer-facing decline.
---

# 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

```json
{
  "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](country-coverage.md) 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 `null` counts as an omission.** `"bankCode": null` returns `bankCode can't be empty`, not a type error — nulls are stripped before the payload is validated. A `null` inside a `must be of one [...]` list means the opposite: the field is optional, but constrained once you send it.

## `PAY_001` — no route for this country

```json
{
  "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

```json
{
  "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](country-coverage.md) above.

## What's Next

- [Country coverage](country-coverage.md) — What each corridor requires, so `VE_001` never fires
- [Schemas](../../reference-data/schemas.md#country-schema) — Read the rules straight from the source
- [Response codes](../../domain-tables/response-code.md) — Customer-facing decline categories