Erros

Três erros explicam quase todo push que nunca chega a uma rede de payout. Os três são problemas de integração, não recusas, então não mapeie nenhum deles para uma mensagem de recusa ao cliente final.

VE_001 — o payload não satisfaz o 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. A falha mais comum de um push, e justamente a que a tabela de cobertura por país existe para evitar.

A chave do envelope é code, não o errorCode que PAY_001 e PAY_271 carregam. Um cliente que lê apenas errorCode recebe undefined numa falha de validação — trate as duas.

errors[].field é um caminho com pontos a partir da raiz do corpo da requisição, com índice quando o valor está dentro de um array (recipient.documents[0].document). errors[].message repete esse caminho e diz qual regra foi quebrada.

errors lista as violações que o gateway encontrou, ordenadas por caminho do campo. Corrija cada entrada e reenvie — e se voltar outro VE_001, trabalhe a nova lista do mesmo jeito.

Formatos das mensagens

As mensagens de enum e de regex trazem os valores aceitos e o próprio pattern, então a resposta costuma bastar para corrigir o payload sem buscar o schema de novo.

Um null explícito conta como omissão. "bankCode": null devolve bankCode can't be empty, não um erro de tipo — nulos são removidos antes da validação. Já um null dentro de uma lista must be of one [...] significa o contrário: o campo é opcional, mas fica restrito assim que você o envia.

PAY_001 — sem rota para este país

{
  "errorCode": "PAY_001",
  "message": "No router found for agent and payment method"
}

HTTP 400. O gateway não encontrou nenhuma rota de provedor que pertença à sua conta e cubra o país de destino para o paymentMethod.type que você pediu. É levantado quando o roteamento resolve para um conjunto vazio — não quando seu payload está malformado.

Causas comuns, na ordem que vale checar:

O endpoint de schema não é uma verificação de roteamento. GET /schema/{countryCode} responde "o que este país exige?", não "consigo pagar este país hoje?" — um país pode devolver schema válido e ainda assim render PAY_001. Trate-o como questão de configuração a levantar com seu contato Inyo, não como algo a repetir.

PAY_271 — sem schema para este país

{
  "errorCode": "PAY_271",
  "message": "Error retrieving JSON schema for country code: {countryCode}"
}

HTTP 400. Devolvido por GET /schema/{countryCode} quando o código não é um país de payout suportado. Verifique se o código é ISO 3166-1 alpha-3 (DEU, não DE) e se ele aparece na tabela de cobertura por país.

Próximos passos

• Cobertura por país — O que cada corredor exige, para o VE_001 não aparecer
• Schemas — Leia as regras direto da fonte
• Códigos de resposta — Categorias de recusa voltadas ao cliente