Referência
Rate limiting
Para proteger a estabilidade da plataforma, a API limita o número de requisições por janela de tempo.
Limites atuais
As rotas públicas de cobrança aceitam até 100 requisições por minuto. Ao exceder, a API responde 429 Too Many Requests.
Consultar chave PIX tem teto próprio, mais apertado, contado por chave de API: 30 requisições por minuto, além de uma cota diária por conta. Estourar a cota devolve 429 PIX_DICT_QUOTA_EXCEEDED.
O motivo é que a consulta de chave depende de um saldo de consultas do Banco Central compartilhado por toda a plataforma. Consultar em varredura esgota esse saldo e derruba os pagamentos por chave de todos os integradores, e não só os seus.
Como lidar
- Implemente retry com backoff exponencial ao receber
429. - Prefira webhooks a polling para saber de pagamentos, o que elimina a maior fonte de tráfego repetido.
- Combine retries com idempotência para nunca duplicar cobranças.
- Consulte uma chave PIX uma vez por pagamento, e reenvie o
end_to_end_iddevolvido. Não consulte em cadastro, em validação de formulário nem em lote.
Precisa de mais throughput?
Limites por chave e tiers maiores estão no roadmap. Se seu volume exige um teto maior, fale com o suporte.Resposta
HTTP/1.1 429 Too Many Requests
{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}