reason de um 429 para saber qual limite bloqueou a solicitação e, em seguida, aguarde o Retry-After ou altere o limite. O roteamento e os fallbacks reduzem as falhas de provedores, mas uma solicitação ainda pode ser limitada por um provedor ou por uma política do espaço de trabalho ou da chave.
Todos esses retornam
429. Se a aplicação de cotas do gateway estiver indisponível por um breve período, o gateway retorna 503 com orientação para nova tentativa.
Limites do gateway
Cada usuário em cada espaço de trabalho tem uma cota de solicitações por minuto, medida em uma janela móvel de um minuto. As chaves de API criadas pelo mesmo usuário compartilham essa cota. Solicitações OAuth contam para o usuário autenticado, e chaves sem proprietário compartilham uma cota do espaço de trabalho. A cota aumenta automaticamente à medida que o espaço de trabalho se consolida. Um espaço de trabalho recebe a linha mais alta para a qual se qualifica, e as alterações entram em vigor em poucos minutos:
Os modelos gratuitos também têm, por padrão, uma cota de 1.500 solicitações por dia UTC. Ela é compartilhada entre todos os modelos gratuitos e entre todos os espaços de trabalho em que o mesmo usuário envia solicitações. Solicitações a modelos pagos não a consomem. Uma solicitação gratuita admitida conta mesmo que o provedor falhe depois, e os fallbacks de provedor dentro de uma solicitação contam uma única vez.
Os dois limites valem em todas as regiões do gateway e podem ser aumentados para um usuário e um espaço de trabalho específicos. Operações com arquivos e consultas de status de tarefas consomem a cota por minuto; endpoints de gerenciamento não.
Uma solicitação rejeitada retorna
429 com Retry-After em segundos. Aguarde esse tempo antes de tentar de novo.
Limites da API de gerenciamento
Os endpoints de gerenciamento, como/v1/keys, /v1/logs e /v1/analytics, compartilham uma cota de 200 unidades por minuto por credencial. Cada chave de gerenciamento, token OAuth e sessão do painel tem sua própria cota, e solicitações sem credencial compartilham uma por endereço IP. Endpoints de modelos, arquivos, lotes e tarefas não a consomem.
Cada solicitação consome unidades de acordo com o trabalho que exige:
/v1/health e as solicitações CORS de preflight são gratuitas. Uma solicitação acima da cota retorna 429 com rate_limit_exceeded, o motivo management_api_rate_limit e Retry-After: 60. A contagem é aproximada e essas respostas não trazem cabeçalhos x-ratelimit-*, então distribua scripts em massa ao longo do tempo em vez de levá-los até o limite.
Limites de chaves e orçamentos
Os limites diários, semanais ou mensais de solicitações e de gastos de uma chave de API, e os orçamentos do espaço de trabalho, retornam429 com key_limit_exceeded quando atingidos. Os campos reason, limit_window e reset_at do corpo indicam qual limite foi atingido e quando a janela dele reinicia, e Retry-After informa os segundos até lá.
Retry-After não aparece quando o limite não reinicia sozinho, como em um orçamento vitalício ou em uma chave com bloqueio leve. Não tente de novo: aumente o orçamento do espaço de trabalho, aumente o limite da chave ou use outra chave.
Proprietários e administradores do espaço de trabalho gerenciam os orçamentos com uma chave de gerenciamento pela /v1/budgets ou em Configurações → Orçamentos, que mostra o gasto de cada orçamento até agora, a parcela usada, uma projeção para o período e quando ele reinicia. Os orçamentos diários, semanais e mensais reiniciam nos limites UTC: meia-noite, segunda-feira às 00:00 e o dia 1º do mês.
Os alertas de gastos podem avisar antes que esses limites sejam atingidos. Uma regra de gastos configurada para bloquear retorna 429 com spend_rule_blocked. Ela funciona por melhor esforço e começa alguns minutos depois que o gasto ultrapassa o limite, então use limites de chave e orçamentos para tetos exatos. Um cabeçalho x-phaseo-spend-warning indica que um bloqueio pode vir em seguida.
Orçamentos de departamento
Proprietários e administradores gerenciam os orçamentos de departamento comphaseo department-budgets, com a API /v1/department-budgets, em Configurações → Orçamentos ou com o recurso phaseo_department_budget do provedor Terraform. O gasto de um departamento considera as mesmas chaves e solicitações OAuth que os limites de taxa de departamento.
Quando um departamento esgota o orçamento diário, semanal ou mensal, as solicitações com chave de API que contam para ele retornam 429 com key_limit_exceeded e o motivo department_daily_cost_budget_reached, department_weekly_cost_budget_reached ou department_monthly_cost_budget_reached. Os campos department_id e department_name do corpo identificam o departamento, e reset_at e Retry-After indicam quando o orçamento reinicia.
- Se a verificação do orçamento estiver indisponível por um breve período, as solicitações são permitidas, então um departamento pode gastar além do orçamento por pouco tempo.
- Proprietários e administradores recebem uma notificação push no celular em cerca de 80% e novamente em 100% de um orçamento. Para esses alertas, os orçamentos são verificados a cada 15 minutos, então solicitações podem ser recusadas antes de o alerta de 100% chegar.
Políticas de limite de taxa
Administradores do espaço de trabalho podem criar políticas nomeadas que definemrequests_per_minute, tokens_per_minute e concurrent_requests e atribuí-las a chaves, membros, departamentos ou usuários finais. Gerencie-as com phaseo rate-limits policies e phaseo rate-limits assignments, com a API /v1/rate-limits, em Configurações → Limites de taxa ou com os recursos phaseo_rate_limit_policy e phaseo_rate_limit_assignment do provedor Terraform.
O que conta para um departamento. Uma chave vinculada a um departamento conta apenas para esse departamento. Qualquer outra chave conta para todos os departamentos de que o criador faz parte, e as solicitações OAuth contam para todos os departamentos do usuário. Um membro com substituição de departamento conta apenas para o departamento da substituição. Para que essas chaves e solicitações OAuth contem apenas para o departamento principal da pessoa, defina a atribuição de departamento como principal em Configurações → Notificações ou com
spend.department_attribution em PATCH /v1/notifications/settings e uma chave de gerenciamento. Os orçamentos de departamento e as regras de gastos usam a mesma configuração.
Quando várias políticas se aplicam, cada uma é contabilizada, e a primeira que se esgota rejeita a solicitação. As políticas se aplicam além dos limites do gateway. As alterações de políticas entram em vigor em cerca de um minuto; as alterações de participação em departamentos feitas no painel ou por SCIM podem levar até cerca de cinco minutos.
Solicitações e tokens por minuto
Os dois são medidos em uma janela móvel de um minuto.tokens_per_minute conta os tokens de entrada e de saída de cada solicitação quando ela termina, incluindo solicitações em streaming e com falha que usaram tokens. Uma solicitação é rejeitada quando o uso no último minuto atinge o limite, então solicitações já em andamento podem levar o uso além dele. Os fallbacks de provedor dentro de uma solicitação contam uma única vez.
Uma solicitação rejeitada retorna 429 com rate_limit_exceeded, o motivo policy_requests_per_minute ou policy_tokens_per_minute, o policy_id, o limit_scope (key, member, department, workspace ou end_user) e Retry-After em segundos.
As respostas a solicitações cobertas por uma política trazem os cabeçalhos do limite mais restritivo:
Uma solicitação rejeitada traz apenas os cabeçalhos do limite que a rejeitou. A contagem acontece em segundo plano, então
remaining é aproximado, e os cabeçalhos de tokens ainda não incluem o uso da própria solicitação atual.
Solicitações simultâneas
concurrent_requests limita quantas solicitações podem estar em andamento ao mesmo tempo. Uma solicitação ocupa uma vaga desde que é admitida até que sua resposta tenha sido enviada por completo, incluindo toda uma resposta em streaming; os fallbacks de provedor e de modelo dentro da solicitação compartilham essa vaga. Quando todas as vagas estão em uso, a solicitação é rejeitada com o motivo policy_concurrent_requests e Retry-After: 1.
A verificação de um limite de simultaneidade espera pelo contador da política, o que adiciona um pouco de latência. Uma vaga cuja liberação se perde é liberada sozinha após 15 minutos. Lotes e sessões em tempo real não são limitados, e uma geração de vídeo ocupa uma vaga apenas enquanto a solicitação que a inicia está em andamento.
Políticas estritas
Por padrão, uma política falha aberta: se os limites dela não puderem ser verificados, a solicitação é permitida. Definafail_closed para torná-la estrita. Uma política estrita verifica os limites de solicitações e de tokens antes de a solicitação ser enviada, e não em segundo plano, o que os torna exatos, mas adiciona latência. Se eles não puderem ser verificados em dois segundos, a solicitação é rejeitada com o motivo policy_unavailable.
As rejeições por simultaneidade e por policy_unavailable não trazem cabeçalhos x-ratelimit-*.
Limites de provedores
Solicitações BYOK usam os limites da sua conta no provedor. Solicitações gerenciadas usam capacidade compartilhada do provedor, que não é uma cota do seu espaço de trabalho. O Phaseo repassa umRetry-After validado quando o provedor envia um. Respostas BYOK também podem incluir cabeçalhos X-Phaseo-Upstream-RateLimit-*; solicitações gerenciadas os omitem porque eles descrevem capacidade compartilhada. Outros cabeçalhos do upstream não são repassados. Consulte Códigos de erro para ver os códigos 429 de provedores.
Lidar com uma solicitação limitada
- Leia o código de erro para distinguir uma limitação temporária de um limite, orçamento ou política que exige uma mudança de configuração.
- Respeite o
Retry-Afterquando ele estiver presente. Ele pode ser em segundos ou uma data HTTP; valide-o antes de agendar uma nova tentativa. - Caso contrário, use backoff exponencial com jitter e um atraso máximo.
- Limite as novas tentativas por número de tentativas e por um prazo total. Cancele trabalhos abandonados e libere o corpo de cada resposta com falha antes de tentar de novo.
- Reduza a simultaneidade se a limitação persistir.
429 por endpoint e por modelo e verifique a frequência de fallbacks nos logs de solicitações. Compare-as com suas configurações de roteamento e, para tráfego BYOK, com as cotas da sua conta no provedor. As proteções controlam quais chaves podem usar quais modelos e provedores.