Visão geral
O uso da API está sujeito a limites de taxa. Esses limites restringem solicitações, tokens ou outros tipos de uso durante um período específico.
Uma resposta 429 pode indicar um limite de taxa temporário, o esgotamento do saldo pré-pago ou um limite de gastos ou uso. Verifique os detalhes do erro antes de tentar novamente ou alterar as configurações de cobrança.
Identifique a causa
Leia a mensagem de erro e error.code, quando fornecido. Erros relacionados à cobrança ainda podem usar o valor mais abrangente insufficient_quota em error.type.
| Erro ou código | O que significa | O que fazer |
| Limite de taxa atingido para solicitações ou tokens | As solicitações estão excedendo um limite de taxa aplicável. | Distribua as solicitações e siga as orientações abaixo para tentar novamente. |
| credit_balance_exhausted | A organização não tem mais créditos pré-pagos. | Adicione créditos nas configurações de cobrança da API. |
| organization_usage_limit_exceeded | A organização atingiu o limite de uso atribuído pela OpenAI. | Solicite a aprovação de um limite de uso maior. |
| organization_spend_limit_exceeded | A organização atingiu o limite de gastos imposto. | Aumente ou remova o limite, ou aguarde a redefinição mensal. |
| project_spend_limit_exceeded | O projeto atingiu o limite de gastos imposto. | Aumente ou remova o limite do projeto, ou aguarde a redefinição mensal. |
Tentar novamente após um erro de cobrança, gastos ou cota não restaura o acesso. Primeiro, corrija o saldo ou limite informado. Alterações nos limites de gastos impostos podem levar algum tempo para entrar em vigor.
A alteração de um limite de gastos exige permissão para gerenciar as configurações da organização ou do projeto correspondente. Se você não tiver acesso, peça ajuda à pessoa que gerencia essas configurações.
Para compras de créditos pré-pagos, consulte: Como configurar e gerenciar a cobrança pré-paga da API.
Para conhecer os diferentes controles de gastos, consulte o guia de limites de gastos da API.
Verifique os limites de taxa aplicáveis
Acesse a página Limites da sua organização para conferir o nível de uso e os limites atuais.
Os limites de taxa podem ser aplicados nos níveis da organização e do projeto. Eles não são cotas individuais dos usuários. Os limites também variam conforme o modelo, e algumas famílias de modelos compartilham um limite.
Verifique qual limite é identificado pelo erro. Por exemplo, solicitações por minuto e tokens por minuto são limites distintos. Você pode atingir um deles e permanecer abaixo do outro.
Confirme a organização usada pela solicitação
Se você pertence a várias organizações, confirme se as solicitações usam a organização e o projeto desejados.
Quando sua chave de API usa uma organização padrão, verifique a configuração de organização padrão. Organizações diferentes podem ter formas de cobrança e níveis de uso distintos.
Reduza erros temporários de limite de taxa
Distribua as solicitações e evite picos
Distribua as solicitações ao longo do tempo, em vez de enviar muitas de uma só vez.
Os limites de taxa podem ser aplicados em períodos menores que o intervalo exibido. Por exemplo, um limite de 60 solicitações por minuto também pode ser aplicado em períodos de 1 segundo. Portanto, um pico breve pode causar um erro mesmo que seu uso médio pareça estar abaixo do limite por minuto.
Prompts longos e limites de tokens de saída desnecessariamente altos também podem contribuir para erros de taxa de tokens.
Tente novamente após uma espera
Para erros temporários de limite de taxa:
Verifique se há um cabeçalho de resposta Retry-After.
Se o cabeçalho contiver um tempo de espera válido, aguarde pelo menos esse período antes de tentar novamente.
Se o cabeçalho estiver ausente ou for inválido, use espera exponencial com jitter: aumente o tempo de espera após cada tentativa malsucedida e acrescente um pequeno atraso aleatório.
Limite o número de novas tentativas e o tempo total gasto nelas.
Os SDKs oficiais da OpenAI já repetem solicitações em caso de erros de limite de taxa qualificados e respeitam Retry-After quando esse cabeçalho está presente. Leve essas novas tentativas em conta antes de adicionar outro loop de repetição.
Solicitações malsucedidas contam para os limites por minuto. Reenviar continuamente a mesma solicitação pode prolongar o problema.
Para ver orientações e exemplos de implementação, consulte o guia de limites de taxa da API. Analise qualquer biblioteca de terceiros para novas tentativas antes de usá-la no aplicativo.
Revise o tamanho do prompt e da saída
Remova instruções desnecessárias, contexto repetido e exemplos dos seus prompts. Teste o prompt revisado para confirmar se ele ainda produz o resultado necessário.
Use o parâmetro de tokens de saída compatível com seu endpoint e modelo:
Chat Completions usa max_completion_tokens.
Responses usa max_output_tokens.
Evite definir um limite muito maior do que o necessário para a solicitação. Esses parâmetros incluem tokens de raciocínio e a saída visível. Portanto, considere ambos ao usar um modelo de raciocínio.
Confira seu nível de uso
Se os erros persistirem após reduzir os picos e analisar o uso de tokens, confira na página Limites as opções disponíveis para aumentar seus limites.
À medida que os gastos com a API aumentam, a OpenAI pode promover automaticamente uma organização a um nível de uso superior. Isso geralmente aumenta os limites de taxa na maioria dos modelos.
Seu limite mensal de uso aprovado é separado dos limites de taxa de solicitações e tokens. O aumento de um deles não deve ser considerado uma confirmação de que o outro também mudou.
Se o problema persistir
Antes de encaminhar o problema
Tenha em mãos a mensagem de erro exata, todos os códigos de erro, os IDs de solicitação relevantes, o horário do erro com seu fuso horário e o limite correspondente exibido na conta. Anote as etapas que você já tentou.
Entre em contato com o Suporte da OpenAI
Entre em contato com o Suporte da OpenAI pela Central de Ajuda se não conseguir resolver o problema após verificar o limite informado. Não inclua chaves de API nem outros segredos de autenticação.