Limite de requisições da API

As requisições autenticadas por token (tanto o token de API quanto o token pessoal) passam por dois limites de volume. Quando você estoura qualquer um deles, a API recusa a requisição com o status 429 Too Many Requests e você precisa aguardar antes de tentar de novo.

Conhecendo os dois limites

Os dois valem ao mesmo tempo, então respeitar o teto por minuto não basta: 300 requisições disparadas nos primeiros dez segundos do minuto estão dentro das 300 por minuto e ainda assim são recusadas pelo limite de 5 segundos.

O limite de 5 segundos existe justamente porque a contagem por minuto sozinha é um teto de consumo, não um freio. Ela permitiria que todas as 300 requisições saíssem de uma vez, que é exatamente o que acontece quando uma integração ou um agente de IA entra em repetição.

Identificando a cota de cada token

A cota é contada por usuário, e é aí que os dois tipos de token se comportam de forma diferente:

Token de API
Funciona como um usuário próprio, então cada token de API tem a sua própria cota. Dois tokens de API do mesmo licenciado não disputam requisições entre si.

Token pessoal
Autentica como você mesmo, então todos os seus tokens pessoais dividem a mesma cota. Criar um segundo token pessoal não dobra o seu limite.

Veja Gerando e usando seu token de API e Tokens pessoais para entender a diferença entre os dois.

Tratando a resposta 429

Quando a requisição é recusada, a resposta traz:

• O status HTTP 429 Too Many Requests.
• O cabeçalho Retry-After, com o número de segundos que você deve esperar.
• Um corpo no mesmo formato de erro das demais respostas da API:

{
  "errors": [
    {
      "message": "Too many requests. Retry later.",
      "extensions": {
        "code": "RATE_LIMITED",
        "retryAfter": 60
      }
    }
  ],
  "data": {}
}

Trate o extensions.code igual aos outros códigos de erro que a API já devolve, e use o Retry-After (ou o retryAfter) para decidir quando repetir a chamada.

Se você estourar os dois limites ao mesmo tempo, a resposta traz o tempo do limite mais longo (60 segundos), não o de 5. Assim você não volta cedo demais e leva outro 429 em seguida.

Atenção: a requisição recusada continua contando para o limite do minuto. Insistir durante o bloqueio prolonga a espera em vez de encurtá-la.

Distribuindo suas requisições

Algumas práticas que evitam esbarrar nos limites:

1. Distribua as chamadas ao longo do minuto em vez de dispará-las em bloco. Até 25 requisições a cada 5 segundos cabem confortavelmente nos dois limites.
2. Ao receber um 429, espere o tempo indicado em Retry-After antes da próxima chamada.
3. Prefira uma query maior a várias pequenas. O limite conta requisições, então buscar vários dados de uma vez (o que o GraphQL faz bem) rende mais dentro da mesma cota.
4. Em cargas grandes, use paginação com um intervalo entre as páginas em vez de disparar todas as páginas em paralelo.