Errores
Tres errores explican casi todo push que nunca llega a una red de payout. Los tres son problemas de integración, no rechazos, así que no mapees ninguno a un mensaje de rechazo para el cliente final.
VE_001 — el payload no cumple el esquema
{
"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. La falla más común de un push, y justo la que la tabla de cobertura por país existe para evitar.
La clave del envelope es code, no el errorCode que traen PAY_001 y PAY_271. Un cliente que solo lee errorCode recibe undefined en una falla de validación — maneja ambas.
errors[].field es una ruta con puntos desde la raíz del cuerpo de la solicitud, con índice cuando el valor está dentro de un arreglo (recipient.documents[0].document). errors[].message repite esa ruta e indica la regla que se rompió.
errors lista las violaciones que el gateway encontró, ordenadas por ruta de campo. Corrige cada entrada y reenvía — y si vuelve otro VE_001, trabaja la nueva lista igual.
Formas de los mensajes
| Regla rota | Mensaje | Ejemplo |
|---|---|---|
| Falta un campo u objeto requerido | <campo> can't be empty | additionalData can't be empty |
| Arreglo más corto de lo exigido | <campo> must have at least N items but found M | recipient.documents must have at least 1 items but found 0 |
| Valor fuera del conjunto permitido | <campo> must be of one [A, B, C] | recipient.paymentMethod.accountType must be of one [CHECKING, SAVINGS, null] |
| Valor que no cumple el patrón | <campo> does not match the expected regex <regex> | recipient.paymentMethod.bankCode does not match the expected regex ^[0-9]{3}$ |
| Valor que no cumple un formato con nombre | <campo> does not match the expected format <formato> | ipAddress does not match the expected format ipv4 |
| Cadena demasiado corta o larga | <campo> must have at least N characters | sender.firstName must have at least 1 characters |
| Número por debajo del mínimo | <campo> must be a number greater than or equal N | amount.total must be a number greater than or equal 0 |
Los mensajes de enum y de regex traen los valores aceptados y el patrón mismo, así que la respuesta suele bastar para corregir el payload sin volver a pedir el esquema.
Un
nullexplícito cuenta como omisión."bankCode": nulldevuelvebankCode can't be empty, no un error de tipo — los nulos se eliminan antes de validar. Unnulldentro de una listamust be of one [...]significa lo contrario: el campo es opcional, pero queda restringido en cuanto lo envías.
PAY_001 — sin ruta para este país
{
"errorCode": "PAY_001",
"message": "No router found for agent and payment method"
}
HTTP 400. El gateway no encontró ninguna ruta de proveedor que pertenezca a tu cuenta y cubra el país de destino para el paymentMethod.type que pediste. Se levanta cuando el ruteo resuelve a un conjunto vacío — no cuando tu payload está malformado.
Causas comunes, en el orden que conviene revisar:
| Causa | Cómo identificarla |
|---|---|
| El corredor no está habilitado en tu cuenta | El mismo payload funciona en otro país; GET /schema/{countryCode} devuelve el esquema sin problema |
| No hay ruta para ese método de pago en ese país | Un BANK_DEPOSIT pasa donde un WALLET falla, o al revés |
| El onboarding con el proveedor subyacente está incompleto | Corredor recién agregado; el esquema existe antes que la ruta |
El endpoint de esquema no es una verificación de ruteo. GET /schema/{countryCode} responde "¿qué exige este país?", no "¿puedo pagar a este país hoy?" — un país puede devolver un esquema válido y aun así dar PAY_001. Trátalo como un asunto de configuración a plantear con tu contacto Inyo, no como algo a reintentar.
PAY_271 — sin esquema para este país
{
"errorCode": "PAY_271",
"message": "Error retrieving JSON schema for country code: {countryCode}"
}
HTTP 400. Lo devuelve GET /schema/{countryCode} cuando el código no es un país de payout soportado. Verifica que el código sea ISO 3166-1 alpha-3 (DEU, no DE) y que aparezca en la tabla de cobertura por país.
Qué sigue
- Cobertura por país — Qué exige cada corredor, para que
VE_001no aparezca - Esquemas — Lee las reglas directo de la fuente
- Códigos de respuesta — Categorías de rechazo de cara al cliente