Diagnostique falhas na API da OpenAI com um plano de testes repetível e limitado
Uma abordagem prática para distinguir falhas de autenticação, limite de requisições, timeout e resposta malformada na API da OpenAI — e testá-las novamente sem tentativas nem gastos ilimitados.
Resumo · TL;DR
Uma verificação repetível da API da OpenAI deve registrar o status, o código de erro, o tempo decorrido e a estrutura da resposta de cada caso. Use tentativas limitadas apenas para falhas transitórias; corrija problemas de autenticação, cota e requisição em vez de tentar novamente.
Principais pontos
- Identifique as falhas pelo status HTTP e pelo código de erro específico, não apenas pelo status.
- Tente novamente erros transitórios de limite de requisições e do servidor dentro de um limite fixo de tentativas e tempo; não trate erros de autenticação ou de créditos esgotados como se fossem temporários.
- Teste a estrutura da resposta separadamente do status HTTP bem-sucedido e do JSON válido.
- Mantenha um conjunto pequeno e repetível de casos e registre as condições necessárias para reproduzir cada falha.
Nesta página (6)
Comece com um diagnóstico limitado
Quando uma chamada à API da OpenAI falhar, determine primeiro se o problema está relacionado a acesso, volume de requisições, tempo decorrido ou dados retornados. Essa distinção define se você deve alterar as credenciais, reduzir o ritmo do tráfego, tentar novamente ou validar a análise feita pela sua aplicação. Um 429, por si só, não basta para escolher uma solução: pode indicar um limite temporário de requisições ou um limite de gastos ou créditos que não será resolvido com outra tentativa.
O guia de códigos de erro da OpenAI documenta os códigos de erro da API e os tipos de exceção correspondentes na biblioteca Python. Use-o como referência ao interpretar a resposta observada: Códigos de erro da API da OpenAI.
Faça a triagem das quatro classes comuns de falha
| Sintoma | O que verificar primeiro | Próxima ação |
|---|---|---|
Erro de autenticação 401 | A chave é válida e está ativa? A organização pretendida está sendo usada? | Corrija a chave ou a organização. Verifique as permissões do projeto e qualquer lista de permissões de IP, se aplicável. |
Resposta 429 | Verifique o código de erro específico e qualquer cabeçalho Retry-After. | Reduza o ritmo das requisições quando se tratar de um limite de taxa. Se os créditos estiverem esgotados ou houver limites de gastos ou uso, resolva esse limite antes de tentar novamente. |
| Timeout ou erro de conexão | Diferencie um timeout da requisição de uma falha de conexão. Registre o tempo decorrido e as condições da rede. | Se for adequado, tente novamente após uma breve espera; em caso de erros de conexão, investigue proxies, certificados ou regras de firewall. |
| Resposta HTTP bem-sucedida, resultado inutilizável | Verifique se o corpo pode ser analisado e se os campos necessários à aplicação existem e têm os tipos esperados. | Trate um campo ausente ou inválido como uma falha de validação da resposta no nível da aplicação, e não automaticamente como um erro de autenticação ou de limite de requisições da API. |
O guia da OpenAI identifica credenciais inválidas como 401 e lista várias causas distintas para 429, incluindo o limite de requisições, créditos esgotados e limites da organização ou do projeto. Para limites de taxa, recomenda seguir Retry-After quando presente. Erros de cobrança, gastos e cota exigem que o limite relevante seja resolvido; tentativas repetidas não restauram o acesso. O guia também lista APITimeoutError e APIConnectionError como exceções distintas da biblioteca Python. Fonte: códigos de erro da OpenAI.
Torne uma pequena avaliação repetível
Use um conjunto fixo de casos em vez de enviar repetidamente prompts improvisados. Comece com casos que isolem uma condição de cada vez:
- Referência: Envie uma entrada pequena e conhecida como válida e confirme a presença do campo de resposta esperado.
- Verificação de autenticação: Execute a mesma referência com as credenciais do projeto pretendido. Não exponha deliberadamente uma chave real em logs ou relatórios de teste.
- Validação da requisição: Em um teste controlado, omita ou escreva incorretamente um parâmetro obrigatório, se o ambiente de teste permitir. Registre o status e a mensagem resultantes; não presuma que todas as requisições malformadas falhem da mesma maneira.
- Tratamento de limite de requisições: Teste a lógica de novas tentativas com uma resposta
429simulada, incluindo um cabeçalhoRetry-After. Evite gerar tráfego real para forçar um limite. - Tratamento de timeout: Simule um timeout no cliente ou no ambiente de testes. Um endpoint de teste lento ou chamadas repetidas em produção podem gerar carga desnecessária e resultados ambíguos.
- Validação da resposta: Teste um corpo JSON válido com um campo obrigatório ausente, um campo do tipo errado e JSON inválido. Esses são problemas distintos de análise ou de contrato.
Para cada caso, registre a data e hora com o fuso horário, o endpoint ou a operação, o modelo, o status HTTP se disponível, o tipo e o código de erro, o número de tentativas, o tempo decorrido e um identificador de requisição ou contexto de diagnóstico com dados confidenciais removidos. Nunca armazene credenciais ou entradas sensíveis em logs compartilhados. Se entrar em contato com o suporte da OpenAI sobre um problema persistente, o guia recomenda informar o modelo, o erro e o código, os dados da requisição e os cabeçalhos, a data e hora com o fuso horário e outros detalhes relevantes; remova primeiro segredos e dados sensíveis.
Estabeleça um limite rígido para novas tentativas
Novas tentativas só são úteis quando a falha pode desaparecer por conta própria. Defina o número máximo de tentativas e o tempo total que a aplicação usará antes de retornar uma falha. Para uma resposta de limite de requisições, respeite Retry-After quando fornecido e mantenha finito o limite de novas tentativas. Para erros do servidor, o guia recomenda tentar novamente após uma breve espera; problemas persistentes devem ser verificados na página de status ou encaminhados para suporte. Um 401, uma requisição malformada ou uma resposta de créditos esgotados não justificam um ciclo automático de novas tentativas.
Em Python, a biblioteca oficial distingue exceções como AuthenticationError, BadRequestError, RateLimitError, APITimeoutError e InternalServerError. Trate as classes de exceção disponíveis na versão da biblioteca instalada e registre o status e o código de erro, quando disponíveis. O exemplo abaixo é ilustrativo: mostra uma classificação, não uma configuração testada nem uma política universal de novas tentativas:
from openai import OpenAI
client = OpenAI() # Supply credentials using your approved secret-management method.
try:
response = client.responses.create(
model="YOUR_SUPPORTED_MODEL",
input="Return the word ready."
)
text = response.output_text
if not isinstance(text, str) or not text.strip():
raise ValueError("Response text is missing or empty")
print(text)
except Exception as exc:
# In production, classify known SDK exceptions explicitly and log
# status/code when available. Do not log credentials or sensitive input.
print(type(exc).__name__, str(exc))
O espaço reservado para o modelo deve ser substituído por um modelo disponível para o seu projeto. O exemplo não comprova que um modelo, parâmetro ou endpoint de provedor específico seja compatível com o seu ambiente. Se você usar outro provedor compatível, confirme se o endpoint e o suporte a parâmetros correspondem à configuração do cliente antes de presumir um comportamento idêntico.
Mantenha as respostas malformadas separadas dos erros da API
Um status HTTP válido não garante que a aplicação recebeu o conteúdo esperado. Valide a resposta no ponto de entrada: confira se a análise foi bem-sucedida, se os campos obrigatórios existem e se os valores têm tipos utilizáveis. Registre uma descrição concisa da falha de validação — como “output_text ausente” ou “string esperada” — em vez de despejar conteúdo sensível da resposta.
Se a API retornar um erro estruturado, preserve o status e o código nos diagnósticos. Se a requisição for bem-sucedida, mas o analisador da própria aplicação rejeitar o corpo, identifique isso separadamente. Assim, fica claro se é preciso investigar o acesso à API ou os limites de requisições, a construção da requisição, o transporte ou as suposições da aplicação.
Conclusão
Uma avaliação útil da API da OpenAI é pequena, reproduzível e limitada: uma referência, casos de falha direcionados, verificações explícitas da saída e um limite fixo de novas tentativas. Registre contexto suficiente para reproduzir cada falha e use o código de erro específico — não apenas o status HTTP — para escolher a próxima etapa.
Perguntas frequentes
Devo tentar novamente todo erro 429 da OpenAI?
Não. Verifique o código de erro específico. Um limite temporário de requisições pode exigir redução do ritmo e respeito a `Retry-After`; créditos esgotados ou limites de gastos e uso exigem que o limite seja resolvido antes de tentar novamente.
Como posso distinguir uma falha da API de uma resposta malformada?
Registre o status HTTP e o código de erro da API separadamente da validação da aplicação. Uma resposta bem-sucedida que não pode ser analisada ou não contém um campo obrigatório é um problema de validação da resposta, não necessariamente um erro da API.
Que detalhes devo coletar sobre uma falha persistente?
Registre o modelo, a mensagem e o código de erro, o contexto da requisição e os cabeçalhos relevantes, a data e hora com o fuso horário, o número de tentativas e o tempo decorrido. Remova as chaves de API e os dados sensíveis antes de compartilhar logs ou informações com o suporte.
Como devo testar limites de requisições sem afetar a produção?
Teste o comportamento de novas tentativas com uma resposta 429 simulada, incluindo um cabeçalho `Retry-After` simulado. Evite gerar tráfego excessivo de propósito em um projeto de produção para acionar limites de requisições.
Artigos relacionados
Guides
Avaliação do GPT-5.6 Sol: quem realmente precisa do modelo topo de linha da OpenAI em comparação ao DeepSeek e Qwen
Uma análise prática do GPT-5.6 Sol comparando o carro-chefe da OpenAI com DeepSeek V4 e Qwen, incluindo preços, integração com a API da OpenAI e quem deve adotá-lo.
Guides
Por que o Claude Opus 4.7 é o melhor modelo de IA para programação neste momento
Comparação entre Claude Opus 4.7 e GPT-5.4 para programação: qualidade de código, raciocínio e custo. Veja como o OneMux oferece acesso unificado a ambos pela API da OpenAI.
Guides
Claude Opus 4.7 vs GPT-5.5 vs Gemini 3.1 Pro: Qual Modelo Vence na Engenharia de Software?
Compare o OpenAI GPT-5.5, o Claude Opus 4.7 e o Google Gemini 3.1 Pro em benchmarks, preços e tarefas reais. Descubra por que o Opus 4.7 domina a engenharia de software e como o OneMux oferece acesso unificado.
Guides
Troca de modelos sem alterar o código: usando o GPT-5.6 Sol com o OneMux
Saiba como mudar para o modelo GPT-5.6 Sol da OpenAI no ChatGPT sem alterar o código. A API unificada do OneMux simplifica o roteamento de modelos para desenvolvedores.