Guia para desenvolvedores

Limites e erros da API Pix: o que cada código significa e como tratar

Boa integração de pagamentos é a que lida bem com o erro. Estes são os códigos que você vai ver, o que cada um quer dizer e a ação certa em cada caso.

Abrir conta Falar com o time

Os códigos e a ação certa

400: regra de negócio
Saldo, limite ou destinatário recusado. Nada foi debitado. Mostre a mensagem e não repita igual.
401: token vencido
Peça um novo token em /oauth/token e repita a chamada.
403: sem permissão ou sem certificado
A chave não tem a permissão da rota, ou a conta exige o certificado de cliente (certificate_required).
429: limite de chamadas
Você passou do limite por minuto da chave. Espere e tente de novo, com espera crescente. Para saber de um pagamento, use webhook em vez de consultar em loop.
501: rota que não existe
O recurso não é oferecido (not_supported). Não é falha temporária. Veja o que existe e o que não existe.

Erro de rede em pagamento: repita com a mesma chave

Se a conexão cair ou der timeout em um pagamento, não gere outra chave de idempotência: repita com a mesma (devolve o mesmo pagamento, sem pagar duas vezes) ou consulte pela chave. Só crie uma chave nova se o pagamento anterior foi CANCELED. Veja idempotência.

Limite de chamadas

Cada chave tem limite de requisições por minuto, que pode ser ajustado conforme o volume e a validação do time. O jeito mais barato de ficar abaixo dele é trocar a consulta por webhook. Fale com o time para ajustar o limite à sua operação.

Perguntas frequentes

Quanto tempo vale o token?

1 hora. Renove quando faltar pouco ou ao receber 401.

O que fazer ao receber 429?

Espere e tente de novo com espera crescente, e reduza consultas trocando por webhook.

Um 501 é falha temporária?

Não. Significa que a rota não é oferecida pela conta.

Um erro 400 debitou o meu saldo?

Não. Em recusa por regra de negócio nada é debitado.