Limites de uso

São quatro baldes independentes, contados em janela fixa. Estourar qualquer um deles responde 429 rate_limited com Retry-After em segundos.

Os quatro tetos

1. Global, por chave: 100 requisições / 10 segundos.
2. Por rota, por chave: 50 requisições / 10 segundos na mesma rota (metade do global) — existe para que uma rota sozinha não consuma o orçamento inteiro da chave. A rota conta pelo padrão (/contacts/:id), não pela URL com o id: mil contatos diferentes usam o mesmo balde.
3. Diário, por chave: 10.000 requisições por padrão (ajustável por chave). A janela é alinhada ao relógio — ela vira no começo do dia UTC, não 24 h depois da sua primeira chamada.
4. Autenticação inválida, por IP: 20 tentativas por minuto. Token errado repetido vira 429 antes de virar 401; veja autenticação.

A message do 429 diz qual teto foi: "Limite de 100 requisições por 10 segundos", "Limite de 50 requisições por 10 segundos nesta rota", "Limite diário de N requisições" ou "Muitas tentativas de autenticação. Aguarde."

Os headers descrevem só o balde global

• X-RateLimit-Limit — teto da janela global.
• X-RateLimit-Remaining — quanto resta da janela global.
• X-RateLimit-Reset — epoch (segundos) de quando a janela global vira.

Os headers também não aparecem num 401 nem num 403: eles só são escritos depois que a chave é resolvida e todas as checagens de permissão passaram.

O que conta como requisição

A contagem acontece depois da autenticação e das checagens de permissão, e antes da rota rodar. Na prática:

• Chamada que termina em 401 (token inválido) ou em 403 (escopo, IP, workspace pausado) não consome os baldes da chave — o 401 consome o balde do IP, que é outro.
• Corpo ou querystring fora do formato também não consomem: essa validação roda antes da autenticação e devolve 400 sem tocar em nada.
• Todo o resto conta, inclusive as respostas 404, 409 e 422: quem entrou no orçamento da chave gastou o orçamento.
• Os baldes são por id de chave. Rotacionar o token mantém o mesmo id, então a contagem segue de onde estava; criar uma chave nova é que começa um orçamento novo.

Como não bater no teto

Peça páginas grandes (limit=500, veja paginação) em vez de muitas chamadas pequenas; espalhe a carga entre rotas em vez de concentrar numa; e no 429, espere o Retry-After.

As rotas de documentação

GET /api/v1/docs e GET /api/v1/openapi.json não pedem chave e têm teto próprio: 30 requisições por minuto por IP. Se você gera cliente a partir do documento, baixe uma vez e guarde — não puxe o openapi.json a cada build.

O rate limit é guardrail, não cadeado

Se a infraestrutura de contagem ficar indisponível, o limite libera em vez de derrubar a API. É escolha deliberada: um contador fora do ar não pode tirar a sua integração do ar junto. Trate o 429 como sinal de ritmo, nunca como camada de segurança.