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, vários tetos#

Os limites desta tabela que têm número próprio (todos menos a linha do login, a linha das coleções e a última linha) dividem um contador por conta, e cada endpoint compara essa contagem compartilhada com o seu próprio teto. Alguns endpoints que este guia não descreve também têm um número próprio e usam o mesmo contador. Então o teto mais baixo em jogo vence: depois de 20 chamadas a GET /api/v1/profiles dentro de um minuto, POST /api/v1/agent/chat responde 429 mesmo que você nunca o tenha chamado, enquanto POST /api/v1/chat, com o teto de 60, continua funcionando.

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.
• Trate 20 por minuto como o orçamento de tudo o que você faz com /v1, 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.