Códigos de resposta
Use o status HTTP para a categoria do resultado e leonapayCode para o motivo específico.
Envelope de erro previsível
Toda falha transacional usa o mesmo contrato.
leonapayCode é 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. A liquidante é uma decisão interna da LeonaPay e não integra o contrato público.{
"success": false,
"leonapayCode": "LP400_PAYER_TAX_ID",
"leonapayDescription": "payer.taxId is required for PIX",
"error": {
"category": "VALIDATION",
"leonapayCode": "LP400_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#lp400-payer-tax-id"
},
"requestId": "req_01J..."
}Status HTTP e decisão de retentativa
Use primeiro o HTTP para a categoria e depois
leonapayCode 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 | Serviço transacional temporariamente indisponível | Sim; mesma idempotência e backoff |
504 | Resultado ainda inconclusivo | Não crie duplicata; consulte a operação original |
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 |
|---|---|---|
LP400_INVALID_JSON | Corpo JSON malformado | Corrija a sintaxe antes de reenviar |
LP400_PAYER_TAX_ID | Documento do pagador ausente em PIX ou SPEI | Preencha payer.taxId |
LP400_PAYER_PHONE | Telefone MB WAY ausente ou fora de +351XXXXXXXXX | Corrija payer.phone |
LP400_BOLETO | Dados do pagador, endereço ou vencimento incompletos | Corrija os campos listados em errors antes de reenviar |
LP400_CARD_DATA | Dados de criação do cartão inválidos | Revise pagador, valor, moeda e returnUrl |
LP400_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 |
LP400_RETURN_URL | URL de retorno do cartão/3DS ausente | Preencha returnUrl HTTPS |
LP401 | Chave ausente, inválida ou de outro ambiente | Revise x-api-key |
LP403 | Escopo insuficiente para a operação | Revise os escopos da chave de API |
LP403_IP | IP de saque não permitido | Cadastre o IP de saída do servidor no painel |
LP409_IDEMPOTENCY_CONFLICT | Mesma chave usada com outro conteúdo | Use uma nova chave para a nova operação |
LP409_IDEMPOTENCY_IN_PROGRESS | A primeira requisição ainda está em curso | Repita a mesma requisição após retryAfter |
LP409_BALANCE | Saldo disponível insuficiente | Não retente sem recompor saldo |
LP422_PIX_KEY_INVALID | Chave PIX inválida ou inexistente | Corrija destination.pixKey e crie uma nova tentativa |
LP422_DESTINATION_INVALID | Conta, CLABE, chave ou destino inválido | Corrija o campo destination indicado |
LP422_DESTINATION_NOT_FOUND | Destino não localizado pela rede | Confirme os dados antes de criar outra tentativa |
LP422_BENEFICIARY_REJECTED | Beneficiário não pode receber a operação | Revise os dados do beneficiário |
LP422_AMOUNT_INVALID | Valor fora das regras do método | Corrija amount antes de reenviar |
LP422_PIX_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_BOLETO_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_SPEI_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_OXXO_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_MBWAY_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_BANK_TRANSFER_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_PSE_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_NEQUI_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_BREB_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_CASH_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_PAGOMOVIL_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_CREDIT_CARD_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP422_DEBIT_CARD_REJECTED | Pagamento recusado de forma definitiva | Revise dados e crie uma nova tentativa |
LP429 | Limite da API LeonaPay excedido | Backoff exponencial com jitter e mesma chave |
LP429_PROVIDER_RATE_LIMIT | Capacidade temporária do método limitada | Respeite retryAfter e preserve a mesma idempotência |
LP502_PIX_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_PIX_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_PIX_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_BOLETO_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_BOLETO_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_BOLETO_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_SPEI_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_SPEI_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_SPEI_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_OXXO_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_OXXO_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_OXXO_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_MBWAY_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_MBWAY_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_MBWAY_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_BANK_TRANSFER_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_BANK_TRANSFER_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_BANK_TRANSFER_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_PSE_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_PSE_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_PSE_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_NEQUI_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_NEQUI_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_NEQUI_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_BREB_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_BREB_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_BREB_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_CASH_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_CASH_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_CASH_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_PAGOMOVIL_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_PAGOMOVIL_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_PAGOMOVIL_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_CREDIT_CARD_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_CREDIT_CARD_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_CREDIT_CARD_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP502_DEBIT_CARD_INVALID_RESPONSE | Serviço retornou instruções incompletas | Retente com a mesma chave |
LP503_DEBIT_CARD_TEMPORARILY_UNAVAILABLE | Método temporariamente indisponível | Retente com a mesma chave e backoff |
LP504_DEBIT_CARD_TIMEOUT | Resultado da rede ainda inconclusivo | Consulte a operação; não crie uma duplicata |
LP500_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.
Erro síncrono e falha assíncrona
Validações conhecidas pela LeonaPay retornam HTTP 400 antes do envio. Pagamentos e saques aceitos podem falhar depois: nesse caso, use
GET /api/v2/transactions/{transactionId}, GET /api/v2/withdrawals/{withdrawalId} ou o webhook assinado. payment.failed e withdrawal.failed devolvem exatamente o mesmo data.error gravado na consulta.Retente apenas quando retryable=true. Quando retryAfter existir, aguarde esse intervalo; preserve a mesma idempotência e consulte antes de criar uma nova operação.
