Visão geral
O uso da API está sujeito a limites de taxa. Esses limites restringem solicitações, tokens ou outras formas de uso em um período específico.
Uma resposta 429 pode indicar um limite de taxa temporário, um saldo pré-pago esgotado ou um limite de gastos ou de uso. Confira os detalhes do erro antes de tentar novamente ou alterar suas configurações de cobrança.
Identifique a causa
Leia a mensagem de erro e o campo error.code, quando fornecido. Erros relacionados à cobrança também podem usar o valor mais genérico insufficient_quota no campo 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. | Espace as solicitações e siga as orientações abaixo para novas tentativas. |
| 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 definido pela OpenAI. | Solicite a aprovação de um limite de uso maior. |
| organization_spend_limit_exceeded | A organização atingiu o limite de gastos com bloqueio de uso. | Aumente ou remova o limite, ou aguarde a renovação mensal. |
| project_spend_limit_exceeded | O projeto atingiu o limite de gastos com bloqueio de uso. | Aumente ou remova o limite do projeto, ou aguarde a renovação mensal. |
Tentar novamente após um erro de cobrança, gastos ou cota não restaura o acesso. Resolva primeiro o problema de saldo ou limite indicado. Alterações nos limites de gastos com bloqueio de uso podem levar algum tempo para entrar em vigor.
Para alterar um limite de gastos, é preciso ter permissão para gerenciar as configurações da organização ou do projeto em questão. Se você não tiver acesso, peça à pessoa responsável por essas configurações.
Para comprar créditos pré-pagos, consulte: Como configurar e gerenciar a cobrança pré-paga da API.
Para saber mais sobre os diferentes controles de gastos, consulte o guia de limites de gastos da API.
Confira os limites de taxa aplicáveis
Acesse a página de Limites da sua organização para conferir o nível de uso e os limites atuais.
Os limites de taxa podem ser aplicados à organização e ao projeto. Eles não são cotas individuais por usuário. Os limites também variam conforme o modelo, e algumas famílias de modelos compartilham um limite.
Verifique qual limite o erro indica. Por exemplo, solicitações por minuto e tokens por minuto são limites distintos. Você pode atingir um deles e continuar abaixo do outro.
Confira os limites da API de geração de imagens
Os limites de taxa da API de geração de imagens dependem do modelo e do seu nível de uso. Selecione seu modelo na página de modelos para ver os limites dele.
Para ver as instruções de configuração, consulte o guia de geração de imagens para desenvolvedores. Para saber mais sobre os níveis de uso, consulte o guia de limites de taxa da API.
Confirme a organização usada pela sua solicitação
Se você faz parte de várias organizações, confirme se suas solicitações usam a organização e o projeto desejados.
Quando sua chave de API usa uma organização padrão, confira a configuração de organização padrão. Organizações diferentes podem ter condições de cobrança e níveis de uso diferentes.
Reduza os erros temporários de limite de taxa
Espace 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 mais curtos 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. Assim, um pico breve pode gerar 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 limite de taxa de tokens.
Aguarde antes de tentar novamente
Para erros temporários de limite de taxa:
Verifique se há um cabeçalho Retry-After na resposta.
Se o cabeçalho contiver um tempo de espera válido, aguarde pelo menos esse tempo antes de tentar novamente.
Se o cabeçalho estiver ausente ou for inválido, use recuo exponencial com variação aleatória: aumente o tempo de espera após cada tentativa malsucedida e acrescente um pequeno intervalo aleatório.
Limite tanto o número de novas tentativas quanto o tempo total gasto nelas.
Os SDKs oficiais da OpenAI já fazem novas tentativas nos erros de limite de taxa elegíveis e respeitam o Retry-After quando ele está presente. Leve essas tentativas em conta antes de adicionar outro ciclo de novas tentativas.
Solicitações malsucedidas contam para os limites por minuto. Reenviar a mesma solicitação continuamente pode prolongar o problema.
Para ver orientações de implementação e exemplos, consulte o guia de limites de taxa da API. Avalie qualquer biblioteca de terceiros para novas tentativas antes de usá-la na sua aplicação.
Revise o tamanho do prompt e da saída
Remova dos prompts instruções desnecessárias, contexto repetido e exemplos. Teste o prompt revisado para confirmar que ele ainda produz o resultado de que você precisa.
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 a solicitação precisa. Esses parâmetros incluem tanto os tokens de raciocínio quanto a saída visível. Por isso, reserve espaço para ambos ao usar um modelo de raciocínio.
Confira seu nível de uso
Se os erros persistirem após reduzir os picos e revisar o uso de tokens, consulte a página de Limites para ver as opções disponíveis para aumentar seus limites.
O nível de uso pago da sua organização sobe automaticamente à medida que o total de compras de créditos atinge os valores exigidos para Build, Launch e Grow. Níveis mais altos geralmente oferecem limites de taxa maiores. Consulte os requisitos de cada nível no guia de limites de taxa da API.
Seu limite mensal de uso aprovado é independente dos limites de taxa de solicitações e tokens. O aumento de um não deve ser considerado uma confirmação de que o outro mudou.
Se o problema persistir
Antes de acionar o suporte
Tenha em mãos a mensagem de erro exata, os códigos de erro, se houver, os IDs das solicitações envolvidas, o horário do erro com seu fuso horário e o limite correspondente exibido na sua conta. Anote as medidas 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 indicado. Não inclua chaves de API nem outros dados secretos de autenticação.