Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Gestão de Erros e Códigos HTTP

Aula 12 de 22 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Gestão de Erros e Códigos HTTP
  2. Códigos HTTP da API OpenAI
  3. Gestor de Erros Abrangente
  4. Erros Específicos da Responses API
  5. Registo de Erros Estruturado
  6. Tabela Resumo
  7. Pontos-chave

Atualizado em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (Responses API) ou reasoning_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 utilizar gpt-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.

CodeExceptionRetry?Action
400BadRequestErrorNoCorrect the request
401AuthenticationErrorNoVerify API key
403PermissionDeniedErrorNoVerify permissions
404NotFoundErrorNoVerify model/endpoint
422UnprocessableEntityErrorNoCorrect the format
429RateLimitErrorYesExponential backoff
500InternalServerErrorYesWait and retry
503InternalServerErrorYesService 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_retries se necessário