Códigos de resposta

Use o status HTTP para a categoria do resultado e onpayCode para o motivo específico.

Envelope de erro previsível

Toda falha transacional usa o mesmo contrato. onpayCode é estável para automação; error.field aponta o campo; retryable informa se a mesma operação pode ser repetida; e requestId permite localizar o log exato nas últimas 24 horas.

{
  "success": false,
  "onpayCode": "ONP400_PAYER_TAX_ID",
  "onpayDescription": "payer.taxId is required for PIX",
  "error": {
    "category": "VALIDATION",
    "code": "ONP400_PAYER_TAX_ID",
    "message": "payer.taxId is required for PIX",
    "field": "payer.taxId",
    "retryable": false,
    "requestId": "req_01J...",
    "docsUrl": "https://docs.leonapay.com.br/docs/errors#onp400-payer-tax-id"
  },
  "requestId": "req_01J..."
}

Status HTTP e decisão de retentativa

Use primeiro o HTTP para a categoria e depois onpayCode para a causa. Nunca faça retentativa cega de um 4xx.

Status	Significado	Retentar
`200 / 201 / 202`	`Operação aceita ou concluída`	`Não aplicável`
`400 / 413`	`Payload, campo ou tamanho inválido`	`Não; corrija a requisição`
`401 / 403`	`Credencial, permissão ou IP inválido`	`Não; corrija o acesso`
`404`	`Recurso não encontrado no tenant`	`Não`
`409`	`Idempotência, saldo ou estado em conflito`	`Somente quando retryable=true`
`422`	`Operação recusada após validação`	`Não; crie nova tentativa após corrigir`
`429`	`Capacidade temporariamente limitada`	`Sim; respeite Retry-After`
`502 / 503 / 504`	`Serviço transacional temporariamente indisponível`	`Sim; mesma idempotência e backoff`
`500`	`Falha inesperada da LeonaPay`	`Não cegamente; use requestId`

Catálogo de códigos

Códigos estáveis para validação, automação, observabilidade e suporte.

Código	Causa	Próxima ação
`ONP400_INVALID_JSON`	`Corpo JSON malformado`	`Corrija a sintaxe antes de reenviar`
`ONP400_PAYER_TAX_ID`	`Documento do pagador ausente em PIX ou SPEI`	`Preencha payer.taxId`
`ONP400_PAYER_PHONE`	`Telefone MB WAY ausente ou fora de +351XXXXXXXXX`	`Corrija payer.phone`
`ONP400_BOLETO`	`Dados do pagador, endereço ou vencimento incompletos`	`Corrija os campos listados em errors antes de reenviar`
`ONP400_CARD_DATA`	`Dados de criação do cartão inválidos`	`Revise pagador, valor, moeda e returnUrl`
`ONP400_PAYMENT_METHOD_TOKEN`	`Código legado: uma versão anterior exigiu token antes de iniciar o checkout`	`Omita paymentMethodToken e use sessionToken + checkoutUrl retornados pela API`
`ONP400_RETURN_URL`	`URL de retorno do cartão/3DS ausente`	`Preencha returnUrl HTTPS`
`ONP401`	`Chave ausente, inválida ou de outro ambiente`	`Revise x-api-key`
`ONP403`	`Escopo insuficiente para a operação`	`Revise os escopos da chave de API`
`ONP403_IP`	`IP de saque não permitido`	`Cadastre o IP de saída do servidor no painel`
`ONP409_IDEMPOTENCY_CONFLICT`	`Mesma chave usada com outro conteúdo`	`Use uma nova chave para a nova operação`
`ONP409_IDEMPOTENCY_IN_PROGRESS`	`A primeira requisição ainda está em curso`	`Repita a mesma requisição após retryAfter`
`ONP409_BALANCE`	`Saldo disponível insuficiente`	`Não retente sem recompor saldo`
`ONP422_PIX_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_BOLETO_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_SPEI_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_MBWAY_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_BANK_TRANSFER_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_PSE_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_NEQUI_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_BREB_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_CREDIT_CARD_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP422_DEBIT_CARD_REJECTED`	`Pagamento recusado de forma definitiva`	`Revise dados e crie uma nova tentativa`
`ONP429`	`Limite temporário excedido`	`Backoff exponencial com jitter e mesma chave`
`ONP502_PIX_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_PIX_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_BOLETO_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_BOLETO_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_SPEI_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_SPEI_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_MBWAY_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_MBWAY_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_BANK_TRANSFER_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_BANK_TRANSFER_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_PSE_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_PSE_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_NEQUI_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_NEQUI_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_BREB_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_BREB_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_CREDIT_CARD_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_CREDIT_CARD_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP502_DEBIT_CARD_INVALID_RESPONSE`	`Serviço retornou instruções incompletas`	`Retente com a mesma chave`
`ONP503_DEBIT_CARD_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Retente com a mesma chave e backoff`
`ONP500_INTERNAL`	`Falha inesperada`	`Consulte pelo requestId e acione suporte se persistir`

Diagnóstico por método

Cada método tem requisitos próprios, mas todos compartilham o mesmo envelope e a mesma política de retentativa.

Método	Validação principal	Falhas que exigem atenção
`PIX`	`BRL e payer.taxId`	`QR ausente/incompleto é transitório; rejeição cadastral não é`
`SPEI`	`MXN e payer.taxId`	`CLABE ausente/incompleta é transitória; conta inválida não é`
`MB WAY`	`EUR e payer.phone +351`	`Timeout é transitório; telefone/rejeição no app não é`
`Crédito e débito`	`returnUrl; paymentMethodToken é opcional`	`ACTION_REQUIRED devolve sessionToken + checkoutUrl; consulte o status e warnings antes de considerar uma nova tentativa`

Como investigar com requestId

A LeonaPay devolve o identificador no corpo e nos headers RequestId e x-request-id. No painel, abra Integrações → Logs da API · 24h, localize o registro pelo identificador exibido e veja a resposta pública e a tratativa recomendada. Nenhuma credencial ou resposta bruta da liquidante é exposta.

Guarde o requestId nos seus logs de aplicação. Não registre chaves de API, tokens de confirmação, PAN, CVV ou o corpo bruto de documentos.