Limites e cotas

Dois tipos diferentes de limite se aplicam à sua conta, e eles são recusados de formas diferentes.

Limites de requisições#

Um limite é um número de requisições por minuto, contado por conta, não por chave nem por IP. A sua chave, o seu token de sessão e o app web dividem o mesmo. A janela é fixa: ela começa na sua primeira requisição e dura 60 segundos.

Um contador por linha#

Cada linha desta tabela é um contador próprio, por conta. Uma linha que cita vários endpoints é um contador só para todos eles: todo endpoint /v1 e POST /api/v1/agent/chat gastam os mesmos 20 por minuto. Alguns endpoints que este guia não descreve também contam no contador de uma linha: os endpoints de comparação, junto com POST /api/v1/chat, e salvar ou editar uma anotação, junto com POST /api/v1/embeddings. Chamadas a outras linhas não o gastam: 20 chamadas a GET /api/v1/profiles deixam POST /api/v1/agent/chat intocado.

Até 30/10/2026 toda linha numerada dividia um contador por conta, então o teto mais baixo em jogo vencia. Se o seu cliente foi escrito em torno disso, agora ele é mais rígido do que precisa ser, nunca mais folgado.

Planeje com isso em mente:

• Não faça polling de GET /v1/models nem de GET /api/v1/profiles. Leia uma vez e guarde em cache; a lista de modelos gasta os mesmos 20 das suas mensagens.
• Trate 20 por minuto como o orçamento de tudo o que você faz com /v1 e com o agente, não de cada endpoint.
• Espere que um assistente de código use várias requisições por turno: a mensagem, a contagem de tokens e as novas tentativas contam todas.
• O limite de 300 por minuto dos outros endpoints é um contador separado, mas as chamadas de chat nativo, do agente e de embeddings também contam nele. Os endpoints /v1 e as chamadas de perfis e de versão não contam.

Os headers#

Toda resposta de um endpoint limitado traz:

As requisições que falham na autenticação não trazem nenhum deles.

A resposta 429#

Nos endpoints com número próprio, o corpo é {"message": "Too Many Attempts."}. Em /api/v1 é sempre JSON. Em /v1 é JSON quando você envia Accept: application/json, o que todo SDK oficial faz, e uma página HTML no caso contrário. No limite de 300 por minuto, é:

{ "codigo": "limite_de_requisicoes", "detail": "…" }

A frase em detail é localizada, então use codigo e Retry-After.

Cotas de tokens#

O operador define um teto diário, um semanal e um mensal de tokens para cada grupo de contas, e um teto de -1 quer dizer nenhum. Os tokens são os das suas chamadas bem-sucedidas, de entrada e de saída, em todas as superfícies e todos os modelos, inclusive os do próprio operador. As janelas são em UTC: o dia zera à meia-noite, o mês no primeiro dia, e a semana toda quarta-feira às 14:00.

Leia a sua com GET /api/v1/usage. Quando você atinge um teto, as chamadas são recusadas com 403. É 403 e não 429 de propósito: tentar de novo não ajuda até a janela zerar.

Como a recusa aparece depende da superfície:

A mensagem diz qual teto foi, mas o texto não é estável, então não o interprete por código.

Outros limites do seu grupo#

Além dos tokens, o grupo pode restringir:

• os modelos que você pode usar. GET /api/auth/me os mostra como allowed_models, onde null quer dizer todos;
• servidores remotos: alguns grupos só podem usar os servidores locais do operador;
• anexos por mensagem, no chat nativo.

Cada um deles é recusado do mesmo jeito que uma cota, com 403.

Limites de tamanho#

São padrões. Os dois primeiros são fixados pela API; o operador pode mudar os outros.