Visão geral
A utilização da API está sujeita a limites de taxa. Estes limites restringem os pedidos, os tokens ou outras formas de utilização durante um período definido.
Uma resposta 429 pode indicar um limite de taxa temporário, um saldo pré-pago esgotado ou um limite de despesas ou de utilização. Verifique os detalhes do erro antes de tentar novamente ou de alterar as definições de faturação.
Identifique a causa
Leia a mensagem de erro e o valor de error.code, quando fornecido. Os erros relacionados com a faturação podem ainda 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 pedidos ou tokens | Os pedidos estão a exceder um limite de taxa aplicável. | Espace os pedidos e siga as orientações abaixo para novas tentativas. |
| credit_balance_exhausted | A organização já não tem créditos pré-pagos disponíveis. | Adicione créditos nas definições de faturação da API. |
| organization_usage_limit_exceeded | A organização atingiu o limite de utilização atribuído pela OpenAI. | Solicite a aprovação de um limite de utilização mais elevado. |
| organization_spend_limit_exceeded | A organização atingiu o limite de despesas imposto. | Aumente ou remova o limite, ou aguarde a reposição mensal. |
| project_spend_limit_exceeded | O projeto atingiu o limite de despesas imposto. | Aumente ou remova o limite do projeto, ou aguarde a reposição mensal. |
Repetir um pedido após um erro de faturação, despesas ou quota não restabelece o acesso. Resolva primeiro a questão do saldo ou do limite indicado. As alterações aos limites de despesas impostos podem demorar algum tempo a entrar em vigor.
Para alterar um limite de despesas, é necessário ter permissão para gerir as definições da organização ou do projeto em causa. Se não tiver acesso, peça ajuda à pessoa que gere essas definições.
Para saber como comprar créditos pré-pagos, consulte: Configurar e gerir a faturação pré-paga da API.
Para saber mais sobre os diferentes controlos de despesas, consulte o guia de limites de despesas da API.
Verifique os limites de taxa aplicáveis
Aceda à página de Limites da sua organização para consultar o escalão de utilização e os limites atuais.
Os limites de taxa podem aplicar-se ao nível da organização e do projeto. Não são quotas individuais de cada utilizador. Os limites também variam consoante o modelo, e algumas famílias de modelos partilham um limite.
Verifique qual é o limite identificado no erro. Por exemplo, os pedidos por minuto e os tokens por minuto têm limites distintos. Pode atingir um deles sem ultrapassar o outro.
Verifique 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 escalão de utilização. Selecione o seu modelo na página de modelos para consultar os respetivos limites.
Para obter instruções de configuração, consulte o guia de geração de imagens para programadores. Para saber mais sobre os escalões de utilização, consulte o guia de limites de taxa da API.
Confirme a organização utilizada pelo seu pedido
Se pertencer a várias organizações, confirme que os seus pedidos utilizam a organização e o projeto pretendidos.
Quando a sua chave de API utiliza uma organização predefinida, verifique a definição de organização predefinida. As condições de faturação e os escalões de utilização podem variar entre organizações.
Reduza os erros temporários de limite de taxa
Espace os pedidos e evite picos
Distribua os pedidos ao longo do tempo, em vez de enviar muitos de uma só vez.
Os limites de taxa podem ser aplicados a períodos mais curtos do que o intervalo apresentado. Por exemplo, um limite de 60 pedidos por minuto também pode ser aplicado a períodos de 1 segundo. Assim, um breve pico pode provocar um erro, mesmo que a sua utilização média pareça estar abaixo do limite por minuto.
Prompts longos e limites de tokens de saída desnecessariamente elevados também podem contribuir para erros de limite de taxa de tokens.
Aguarde antes de tentar novamente
Em caso de erros temporários de limite de taxa:
Verifique se existe 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 em falta ou for inválido, utilize uma espera exponencial com variação aleatória: aumente o tempo de espera após cada tentativa sem êxito e acrescente um pequeno atraso aleatório.
Limite tanto o número de novas tentativas como o tempo total dedicado às mesmas.
Os SDKs oficiais da OpenAI já repetem os pedidos com erros de limite de taxa elegíveis para nova tentativa e respeitam o cabeçalho Retry-After quando está presente. Tenha essas tentativas em conta antes de adicionar outro ciclo de novas tentativas.
Os pedidos sem êxito contam para os limites por minuto. Reenviar continuamente o mesmo pedido pode prolongar o problema.
Para obter orientações de implementação e exemplos, consulte o guia de limites de taxa da API. Avalie qualquer biblioteca de terceiros para gerir novas tentativas antes de a utilizar na sua aplicação.
Reveja o tamanho do prompt e da saída
Remova dos seus prompts as instruções desnecessárias, o contexto repetido e os exemplos. Teste o prompt revisto para confirmar que continua a produzir o resultado de que precisa.
Utilize o parâmetro de tokens de saída compatível com o seu endpoint e modelo:
Chat Completions utiliza max_completion_tokens.
Responses utiliza max_output_tokens.
Evite definir um limite muito superior ao necessário para o pedido. Estes parâmetros incluem os tokens de raciocínio e a saída visível, pelo que deve reservar capacidade para ambos ao utilizar um modelo de raciocínio.
Verifique o seu escalão de utilização
Se os erros persistirem após reduzir os picos e rever a utilização de tokens, consulte a página de Limites para conhecer as opções disponíveis para aumentar os seus limites.
O escalão de utilização paga da sua organização sobe automaticamente à medida que o total de compras de créditos atinge os limiares dos escalões Build, Launch e Grow. Os escalões superiores oferecem geralmente limites de taxa mais elevados. Consulte os requisitos dos escalões no guia de limites de taxa da API.
O seu limite de utilização mensal aprovado é independente dos limites de taxa de pedidos e de tokens. O aumento de um não deve ser interpretado como confirmação de que o outro mudou.
Se o problema persistir
Antes de pedir apoio
Tenha à mão a mensagem de erro exata, os eventuais códigos de erro, os IDs dos pedidos relevantes, a hora do erro com o seu fuso horário e o limite em causa apresentado na sua conta. Anote os passos que já tentou.
Contacte o Apoio da OpenAI
Contacte o Apoio da OpenAI através do Centro de Apoio 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.