Limites de pedidos
Cada pedido é contado numa janela fixa de 60 segundos. O contador que se aplica depende da forma como se autentica: as chaves de API têm o limite mais alto, quem tem sessão iniciada um limite generoso e o tráfego anónimo um limite pequeno. Quando o limite se esgota, a API responde 429 e diz quanto tempo esperar.
Os três escalões
O limitador escolhe exatamente um escalão por pedido. Os limites abaixo são os valores por omissão; os operadores podem ajustá-los, por isso leia os cabeçalhos da resposta em vez de fixar números no código.
apiKey | por chave de API | 1000 pedidos / min |
authenticated | por utilizador (sessão) | 600 pedidos / min |
anonymous | por IP do cliente | 30 pedidos / min |
Os caminhos de disponibilidade e de documentação (/health, /meta/version, /docs e /openapi) nunca são limitados.
Cabeçalhos da resposta
Todas as rotas limitadas comunicam a sua política na resposta:
X-RateLimit-Limit | Pedidos permitidos na janela atual para o seu escalão. |
X-RateLimit-Window-Seconds | Duração da janela em segundos (60). |
X-RateLimit-Bucket | Que escalão se aplicou: anonymous, authenticated ou apiKey. |
Retry-After | Só em 429: quantos segundos esperar antes de repetir. |
As respostas bem-sucedidas trazem ainda variantes por escalão, com o nome como sufixo, por exemplo X-RateLimit-Remaining-apiKey (pedidos que restam na janela) e X-RateLimit-Reset-apiKey (segundos até a janela reiniciar).
A resposta 429
Um pedido travado pelo limitador devolve o envelope de erro habitual, com o código estável RATE_LIMITED. Decida a partir do código, mostre a mensagem.
{ "error": { "code": "RATE_LIMITED", "message": "ThrottlerException: Too Many Requests", "traceId": "01JGME0Z4E8B3T3Y5F0V9K2QRD" }}Repetir com backoff
Respeite o Retry-After sempre que estiver presente e, caso contrário, use backoff exponencial. Junte uma Idempotency-Key às repetições dos pedidos que alteram dados, para que uma repetição nunca crie um duplicado.
async function callWithRetry(request, maxRetries = 3) { for (let attempt = 0; ; attempt++) { const res = await request(); if (res.status !== 429 || attempt === maxRetries) return res; const seconds = Number(res.headers.get('Retry-After') ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); }}Superfícies mais restritas
- Os endpoints de IA (conversa, comprovativos, voz, exportações) acrescentam um segundo limitador, por utilizador e agregado: por omissão, um nível de pico de 10 pedidos por minuto e um nível sustentado de 200 por hora.
- Os endpoints de autenticação em /auth/* correm um limitador anti-força-bruta próprio: 10 tentativas por IP por minuto e 5 por conta, com bloqueio exponencial até uma hora, respondendo 429 com o código TOO_MANY_REQUESTS.
- Todos os limites são ajustáveis pelo operador. Trate os cabeçalhos da resposta, e não os números desta página, como a fonte de verdade.