429 até a janela reiniciar.
Como a cota funciona
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
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.

