Limites de requisição
Saiba quantas chamadas por minuto sua credencial pode fazer, como os limites se somam e o que fazer no 429 e no 503.
Limite geral da credencial
Cada credencial pode fazer um número máximo de requisições por minuto. Não existe limite separado por rota nem por grupo de rotas: toda chamada conta na mesma contagem da credencial. Uma venda PIX, uma listagem e uma troca de cartão consomem exatamente o mesmo 1 de 120.
- O padrão é 120 requisições por minuto.
- O valor da sua credencial aparece em
rate_limit_per_minute, na resposta deGET /me. - Você não altera o limite. Veja Como aumentar o limite.
A contagem usa uma janela móvel: a API conta as requisições feitas nos últimos 60 segundos, a cada nova requisição.
O que conta e o que fica de fora:
POST /auth/tokennão conta no limite.- Requisições recusadas com
429também contam. Repetir sem esperar mantém você bloqueado. - Requisições recusadas na autenticação (
401) ou por IP não autorizado (403) não contam.
Headers de limite
As respostas trazem estes headers:
| Header | O que significa |
|---|---|
X-RateLimit-Limit | O rate_limit_per_minute da credencial. |
X-RateLimit-Remaining | Quantas requisições ainda cabem na janela de 60 segundos. |
X-RateLimit-Reset | Tamanho da janela, em segundos. Hoje é sempre 60. |
Retry-After | Só no 429. Quantos segundos esperar. Hoje é sempre 60. |
Resposta 429
Quando o limite estoura, a resposta é:
{
"error": {
"code": "rate_limit_exceeded",
"message": "Limite de requisições excedido. Aguarde e tente novamente.",
"request_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
}
}O que fazer:
- Pare de enviar requisições para essa credencial.
- Espere os segundos de
Retry-After. - Repita. Numa rota de cobrança, repita com a mesma
Idempotency-Key.
Para não chegar no limite, veja as dicas em Como aumentar o limite.
Como aumentar o limite
Quem aumenta o rate_limit_per_minute da credencial é o suporte.
Antes de pedir, reduza as chamadas:
- Use
per_page=100nas listagens, para buscar mais itens por chamada. Veja Paginação e filtros. - Receba os webhooks em vez de consultar a API em loop para saber se algo mudou. Veja Webhooks.
Veja o limite atual
Chame GET /me, como em Envie o token em Authorization, e anote rate_limit_per_minute e credential_id: o suporte precisa dele.
Fale com o suporte
Informe:
| O quê | Exemplo |
|---|---|
O credential_id da credencial | 7c9e6679-7425-40de-944b-e07fc1f90ae7 |
| O limite por minuto que você precisa | 300 |
| O uso esperado | Picos de venda num lançamento, ou sincronização do catálogo de ofertas. |
O ajuste vale para a credencial informada. Se você usa mais de uma credencial, informe cada credential_id.
Confira o novo limite
Depois do ajuste, chame GET /me de novo e confira rate_limit_per_minute. O header X-RateLimit-Limit das respostas também mostra o valor. A API guarda os dados da credencial em cache por até 1 minuto: se ainda aparecer o valor antigo, espere 1 minuto e confira de novo.
Não é preciso gerar outra chave nem outro token: o token que você já usa continua valendo.
Resposta 503
Só as rotas que movimentam dinheiro respondem 503: as três de cobrança, a criação de assinatura, o reembolso, a troca de plano e a troca de cartão. Isso acontece quando o controle de limite fica fora do ar:
{
"error": {
"code": "service_unavailable",
"message": "Serviço temporariamente indisponível. Tente novamente em instantes.",
"request_id": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f60"
}
}A requisição não foi processada. Espere alguns segundos e repita. Nas rotas com Idempotency-Key, use a mesma chave. A troca de cartão não usa Idempotency-Key.
Nas outras rotas, se o controle de limite ficar fora do ar, a requisição segue normalmente.