A API aplica limites em níveis independentes, e uma requisição precisa passar por todos.
Teto global
1.200 requisições por minuto (20 por segundo), em janela deslizante, por conta. Todas as chaves da conta dividem o mesmo teto, então usar várias chaves não aumenta o limite. O painel tem um limite separado.
Limites por rota
Rotas específicas têm limites próprios, informados na página de cada endpoint. Alguns deles:
- Criação de cobranças: 200 por minuto, por conta e por subconta.
- Operações em conjunto de subcontas: 600 por minuto por conta principal, somando cobranças, KYC e saques feitos em nome delas.
- Consulta de chave PIX: 20 por minuto, em recurso liberado por conta. Consulte a chave quando for pagar, não para validar cadastro em massa.
- Cartão (
POST /api/card-charges): 60 por minuto por IP e 60 por minuto por conta. - Cobrança internacional: 60 por minuto na rota e, hoje, 6 cobranças por minuto por conta. Esse número pode mudar, então não o trate como constante do seu sistema.
Como saber qual limite estourou
O corpo do 429 indica o nível:
- Teto global:
Limite de requisições excedido. Tente novamente em breve. - Limite de rota:
Muitas requisições. Tente novamente em breve.
Na criação de cobrança, os cabeçalhos Retry-After e X-RateLimit-Reset dizem quando voltar.
Como reagir
- Recue exponencialmente, com aleatoriedade. Reenviar na hora piora, porque a tentativa anterior continua contando na janela.
- Uma cobrança que recebeu
429não foi criada. Já uma que recebeu timeout de rede pode ter sido. - Na cobrança internacional, a fila responde
503comcode: PROVIDER_BUSYeretryAfter, em segundos. Nesse caso nada foi aberto, e repetir depois do prazo é seguro.
Como consumir menos
A maior parte do consumo vem de polling. Em vez de consultar GET /api/charges em laço, use o webhook EVENT:CHARGE_PAID. Consulte a API para reconciliar, não para descobrir.
Detalhes no guia Limites de requisições.