Gestão de Erros e Códigos HTTP
Nesta página
Atualizado em 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(Responses API) oureasoning_effort="none"(Chat Completions). Fontes: Using GPT-6 · GPT-5.6 Terra.
Esclarecido em 3 de novembro de 2026 com base na página de Deprecations da OpenAI: o exemplo de modelo removido utilizava anteriormente
gpt-4o, que permanece disponível até 14 de janeiro de 2027; passa agora a utilizargpt-4-turbo, que foi descontinuado em 23 de outubro de 2026 (substituto indicado:gpt-5.6-sol). Fonte: Deprecations.
Gestão de Erros e Códigos HTTP
Em produção, os erros são inevitáveis. A rede falha, uma chave de API expira, um colega implementa um parâmetro inválido ou a própria API sofre uma indisponibilidade de três minutos. Compreender os códigos HTTP devolvidos pela API e tratá-los corretamente é essencial para construir aplicações robustas. Todo o desafio resume-se a uma pergunta que deve fazer para cada exceção: isto desaparecerá se eu tentar novamente, ou vou entrar num loop infinito num problema que só um humano pode resolver?
Códigos HTTP da API OpenAI
A API devolve códigos HTTP padrão para indicar o resultado de cada pedido. O SDK Python não permite tratar estes códigos manualmente; em vez disso, traduz cada um numa exceção tipada que pode capturar separadamente. Isto permite-lhe escrever blocos except precisos, em vez de um except Exception genérico que obscureceria a natureza do problema.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
Um 401 indica que a chave de API é inválida ou está em falta. Geralmente, isto ocorre durante a primeira implementação, quando a variável de ambiente não foi propagada para o contentor. Tentar novamente é inútil: a chave será tão inválida daqui a dez segundos.
try:
# Chave de API inválida ou em falta
bad_client = OpenAI(api_key="sk-invalid")
bad_client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except AuthenticationError as e:
print(f"Code: {e.status_code}") # 401
print(f"Message: {e.message}")
# Ação: verifique a chave de API, regenere se necessário
400 — BadRequestError
Um 400 indica que o pedido está mal formado. Aqui, é fornecida uma temperatura de 5.0 quando o valor máximo aceite é 2.0. A mensagem de erro quase sempre identifica o parâmetro defeituoso, tornando este o erro mais rápido de corrigir — desde que o registe corretamente em vez de o ignorar silenciosamente.
try:
# Parâmetros inválidos
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requer effort none
input="Test",
temperature=5.0 # Valor inválido (máx 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Ação: corrija os parâmetros do pedido
429 — RateLimitError
Um 429 indica que está a enviar demasiados pedidos ou que excedeu a sua quota. Ao contrário dos dois anteriores, este erro é temporário por natureza: o contador repõe-se. Este é o caso clássico para uma nova tentativa, mas uma tentativa que espera — e espera mais tempo a cada tentativa.
try:
# Demasiados pedidos ou quota excedida
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except RateLimitError as e:
print(f"Code: {e.status_code}") # 429
print(f"Message: {e.message}")
# Ação: aguarde e tente novamente com backoff exponencial
500/503 — InternalServerError
Os erros 500 e 503 provêm da OpenAI, não de si. O seu pedido era válido; a infraestrutura simplesmente não conseguiu processá-lo. Tente novamente após um atraso: na vasta maioria dos casos, a segunda ou terceira tentativa é bem-sucedida.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 ou 503
print(f"Message: {e.message}")
# Ação: tente novamente após um atraso; o erro está do lado da OpenAI
Gestor de Erros Abrangente
Vamos reunir estes comportamentos numa única função. A lógica é de triagem: os erros fatais são convertidos em RuntimeError e lançados imediatamente, os erros transitórios desencadeiam uma espera que duplica a cada volta e, se o orçamento de tentativas se esgotar, a chamada falha limpa em vez de devolver um valor vazio que o chamador possa interpretar mal.
from openai import OpenAI, APIError, AuthenticationError, RateLimitError
from openai import BadRequestError, APIConnectionError, InternalServerError
import time
client = OpenAI()
def robust_api_call(prompt: str, model: str = "gpt-5.6-terra",
max_retries: int = 3) -> str:
"""Chamada à API com gestão de erros abrangente."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Não tentar novamente — a chave é inválida
raise RuntimeError("Chave de API inválida. Verifique OPENAI_API_KEY.")
except BadRequestError as e:
# Não tentar novamente — o pedido está mal formado
raise RuntimeError(f"Pedido inválido: {e.message}")
except RateLimitError:
# Tentar novamente com backoff exponencial
delay = 2 ** attempt
print(f"Limite de taxa atingido. A aguardar {delay}s...")
time.sleep(delay)
except InternalServerError:
# Tentar novamente — erro do lado do servidor
delay = 2 ** attempt
print(f"Erro do servidor. Tentativa {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Tentar novamente — problema de rede
delay = 2 ** attempt
print(f"Erro de ligação. Tentativa {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Falhou após {max_retries} tentativas")
# Utilização
try:
result = robust_api_call("Hello!")
print(result)
except RuntimeError as e:
print(f"Erro fatal: {e}")
Erros Específicos da Responses API
Duas situações merecem um tratamento separado porque aparecem sob um código genérico, mas exigem uma correção muito específica.
Contexto Demasiado Longo
Um prompt que excede a janela de contexto devolve um 400, tal como um erro ortográfico num parâmetro. Para distinguir entre os dois, inspecione a mensagem: a presença de context_length_exceeded indica-lhe que deve truncar o texto ou mudar para um modelo com uma janela de contexto maior, em vez de rever os seus parâmetros.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Excede a janela de contexto
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("O prompt é demasiado longo para este modelo.")
print("Soluções: trunque o texto ou mude para um modelo")
print("com uma janela de contexto maior.")
Modelo Indisponível
Os identificadores de modelos não são eternos. Uma implementação que ainda referencia um modelo reformado falha com um 404, fazendo com que toda a aplicação colapse, mesmo que tenha funcionado no dia anterior. Trate este caso explicitamente: é um lembrete automático para atualizar a sua configuração.
try:
response = client.responses.create(
model="gpt-4-turbo", # reformado da API em 23 de outubro de 2026
input="Test"
)
except NotFoundError as e:
print(f"Modelo não encontrado: {e.message}")
print("Utilize gpt-5.6-sol, o substituto indicado pela OpenAI, ou um modelo mais recente.")
Registo de Erros Estruturado
Um erro não registado é um erro que descobrirá através de um ticket de cliente. Registar em JSON em vez de texto livre muda tudo quando precisa de agregar: pode contar os 429 por hora, filtrar por response_id ou rastrear o desvio de consumo, o que é impossível com linhas de registo escritas à mão.
import logging
import json
from datetime import datetime
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("openai_client")
def call_with_log(prompt: str) -> str:
"""Chamada à API com registo estruturado."""
request_id = None
try:
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
logger.info(json.dumps({
"event": "api_success",
"model": response.model,
"tokens": response.usage.total_tokens,
"response_id": response.id,
"timestamp": datetime.now().isoformat()
}))
return response.output_text
except APIError as e:
logger.error(json.dumps({
"event": "api_error",
"status_code": e.status_code,
"message": e.message,
"timestamp": datetime.now().isoformat()
}))
raise
result = call_with_log("Hello!")
Tabela Resumo
Mantenha esta grelha à mão: resume a decisão a tomar para cada código.
| Code | Exception | Retry? | Action |
|---|---|---|---|
| 400 | BadRequestError | No | Correct the request |
| 401 | AuthenticationError | No | Verify API key |
| 403 | PermissionDeniedError | No | Verify permissions |
| 404 | NotFoundError | No | Verify model/endpoint |
| 422 | UnprocessableEntityError | No | Correct the format |
| 429 | RateLimitError | Yes | Exponential backoff |
| 500 | InternalServerError | Yes | Wait and retry |
| 503 | InternalServerError | Yes | Service temporarily unavailable |
Pontos-chave
- Categorize os erros: recuperáveis (429, 500, 503) vs fatais (400, 401, 403)
- Utilize backoff exponencial para erros recuperáveis
- Nunca tente novamente em caso de erros de autenticação ou de pedido inválido
- Registe todos os erros com contexto (código, mensagem, carimbo de data/hora)
- O SDK trata automaticamente 2 novas tentativas — configure
max_retriesse necessário