Skip to main content
Cada API Key tem uma cota de 100 requisições por janela de 60 segundos. Passou disso, a API responde 429 até a janela reiniciar.

Como a cota funciona

Requisições com erro também gastam a cota. Um loop que recebe 403 ou 400 e tenta de novo sem parar consome as 100 mais rápido do que um fluxo saudável.
Além da cota por chave existem proteções por IP, aplicadas antes da autenticação. Elas também podem devolver 429. Os cabeçalhos RateLimit-* ajudam a distinguir: RateLimit-Limit: 100 é a cota da chave.

Cabeçalhos

Toda resposta autenticada informa o estado da cota.

A resposta 429

Leia o cabeçalho Retry-After (ou o campo retryAfter, em segundos) para saber quando voltar.

Respeitando o limite

1

Prefira webhooks a consultas

Quase toda a cota de uma integração mal feita vai para polling de status. Receber transaction.approved não gasta nenhuma requisição.
2

Leia RateLimit-Remaining

Quando chegar perto de zero, reduza o ritmo antes de tomar o 429.
3

Espere o Retry-After

No 429, aguarde o tempo informado, mais um jitter aleatório. Nunca tente de novo a cada segundo.
4

Limite as tentativas

Defina um máximo, como 5. Operações financeiras repetem com a mesma chave de idempotência.
5

Separe serviços em chaves diferentes

Cada chave tem a sua cota. Dar uma chave ao checkout e outra à conciliação evita que um job de relatório esgote a cota do pagamento. É para isolar carga, não para ultrapassar o limite de um mesmo serviço.

Exemplo: respeitar o Retry-After

Quanto uma integração costuma gastar

O terceiro caso mostra por que polling não escala: uma única cobrança consultada de 5 em 5 segundos já passa da cota.

Erros

Todos os códigos e o que repetir.

Antes de ir para produção

O que revisar antes de escalar.