Limites de taxa e cotas

Dois tipos de limite mantêm a API rápida para todos:

• O limite de taxa de uma chave: quantas requisições por segundo ela pode enviar, com uma rajada para picos curtos.
• As cotas da organização: quantas requisições todas as chaves dela, somadas, podem enviar por minuto, por dia e por mês.

Os dois dependem do plano da organização. Toda resposta informa em que ponto você está, então um cliente bem-comportado nunca precisa adivinhar.

Limite de taxa de uma chave

Cada chave recebe uma taxa constante e uma rajada. A rajada permite enviar esse número de requisições de uma vez; depois disso, as requisições são aceitas na taxa constante.

A classe vem do plano da organização. GET /v1/me mostra a classe, a taxa e a rajada da chave que faz a chamada (rate_limit). O limite vale para a chave como um todo, não importa quantos servidores da API atendam às suas requisições.

Os endpoints de streaming, POST /v1/chat (com ou sem "stream": true) e GET /v1/jobs/stream, ficam fora do limite de taxa da chave: não o consomem, e os cabeçalhos RateLimit deles não têm o item "key". Eles contam para as cotas da organização, uma vez cada, quando a requisição começa. As perguntas têm limites próprios, descritos abaixo.

Cotas da organização

Um plano pode definir cotas de requisições para a organização: por minuto, por dia e por mês. As janelas são períodos do calendário em UTC: um minuto começa aos :00 segundos, um dia às 00:00 UTC, um mês no primeiro dia às 00:00 UTC. Toda requisição com uma chave ou um token OAuth da organização conta, em qualquer endereço. Uma requisição de streaming conta uma vez, quando começa, não importa quanto tempo dure; com a cota esgotada, ela é recusada com 429 como qualquer outra requisição. Uma requisição recusada com 429 não conta.

Os cabeçalhos

Toda resposta a uma requisição com chave traz os limites que se aplicam a ela:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy e RateLimit seguem o rascunho do IETF RateLimit header fields for HTTP. Cada item é um limite:

X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset informam o mais restritivo desses limites de forma mais simples, para clientes escritos antes de existir RateLimit. X-RateLimit-Reset é dado em segundos.

Quando um limite é atingido

A API responde 429 Too Many Requests com um cabeçalho Retry-After em segundos:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Aguarde o Retry-After e repita a requisição. Repita POST e PATCH com a mesma Idempotency-Key. As funções auxiliares de nova tentativa em Erros fazem as duas coisas.

Outros limites do plano também respondem 429 com Retry-After, por exemplo o número de perguntas por dia (limits.questions) ou de respostas em andamento ao mesmo tempo (limits.concurrent_answers). Trate-os da mesma forma.

Como ficar dentro dos limites

• Leia RateLimit e diminua o ritmo quando r ficar baixo, em vez de esperar um 429.
• Distribua o trabalho em massa ao longo do tempo e use os endpoints de lote onde eles existirem: um lote de 100 documentos é uma única requisição.
• Não consulte alterações em um loop apertado. Inscreva-se em webhooks ou leia o feed de eventos a cada poucos segundos.
• Execute workers em paralelo com um limitador compartilhado. Vários processos com uma mesma chave dividem um mesmo limite de taxa.
• Pergunte ao seu contato no Sursa sobre uma classe mais alta, se a sua integração precisar de mais.