Gestión de errores y códigos HTTP
En esta página
Actualizado el 3 de noviembre de 2026 según la documentación de OpenAI:
temperatureytop_psolo se aceptan con un esfuerzo de razonamiento denone, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificarreasoning={"effort": "none"}(Responses API) oreasoning_effort="none"(Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.
Aclarado el 3 de noviembre de 2026 según la página de Obsolescencias de OpenAI: el ejemplo de modelo eliminado usaba anteriormente
gpt-4o, que sigue disponible hasta el 14 de enero de 2027; ahora utilizagpt-4-turbo, que se discontinuó el 23 de octubre de 2026 (sustituto indicado:gpt-5.6-sol). Fuente: Obsolescencias.
Gestión de errores y códigos HTTP
En producción, los errores son inevitables. La red se cae, una clave de API caduca, un compañero despliega un parámetro inválido o la propia API sufre una interrupción de tres minutos. Comprender los códigos HTTP que devuelve la API y gestionarlos correctamente es esencial para construir aplicaciones robustas. Todo el desafío se reduce a una pregunta que debes hacerte ante cada excepción: ¿desaparecerá esto si lo reintentamos o entraremos en un bucle infinito ante un problema que solo un humano puede solucionar?
Códigos HTTP de la API de OpenAI
La API devuelve códigos HTTP estándar para indicar el resultado de cada solicitud. El SDK de Python no te permite gestionar estos códigos manualmente; en su lugar, traduce cada uno en una excepción tipada que puedes capturar por separado. Esto te permite escribir bloques except precisos en lugar de un except Exception genérico que oscurecería la naturaleza del problema.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
Un 401 indica que la clave de API no es válida o falta. Sueles ver esto durante el primer despliegue cuando la variable de entorno no se ha propagado al contenedor. Reintentar es inútil: la clave será igual de inválida dentro de diez segundos.
try:
# Clave de API inválida o faltante
bad_client = OpenAI(api_key="sk-invalid")
bad_client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except AuthenticationError as e:
print(f"Código: {e.status_code}") # 401
print(f"Mensaje: {e.message}")
# Acción: verificar la clave de API, regenerar si es necesario
400 — BadRequestError
Un 400 te indica que la solicitud está mal formada. Aquí, se proporciona una temperatura de 5,0 cuando el valor máximo aceptado es 2,0. El mensaje de error casi siempre nombra el parámetro defectuoso, lo que convierte este en el error más rápido de solucionar, siempre que lo registres correctamente en lugar de silenciarlo.
try:
# Parámetros inválidos
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requiere effort none
input="Test",
temperature=5.0 # Valor inválido (máx 2.0)
)
except BadRequestError as e:
print(f"Código: {e.status_code}") # 400
print(f"Mensaje: {e.message}")
# Acción: corregir los parámetros de la solicitud
429 — RateLimitError
Un 429 indica que estás enviando demasiadas solicitudes o has superado tu cuota. A diferencia de los dos anteriores, este error es temporal por naturaleza: el contador se reinicia. Este es el caso de libro de texto para un reintento, pero un reintento que espera, y espera más tiempo con cada intento.
try:
# Demasiadas solicitudes o cuota superada
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except RateLimitError as e:
print(f"Código: {e.status_code}") # 429
print(f"Mensaje: {e.message}")
# Acción: esperar y reintentar con retroceso exponencial
500/503 — InternalServerError
Los errores 500 y 503 provienen de OpenAI, no de ti. Tu solicitud era válida; la infraestructura simplemente no pudo procesarla. Reintenta tras un retraso: en la gran mayoría de los casos, el segundo o tercer intento tiene éxito.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Código: {e.status_code}") # 500 o 503
print(f"Mensaje: {e.message}")
# Acción: reintentar tras un retraso; el error está del lado de OpenAI
Gestor de errores integral
Vamos a unir estos comportamientos en una única función. La lógica es un triaje: los errores fatales se convierten en RuntimeError y se lanzan inmediatamente, los errores transitorios activan una espera que se duplica en cada vuelta y, si se agota el presupuesto de intentos, la llamada falla limpiamente en lugar de devolver un valor vacío que el llamador podría malinterpretar.
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:
"""Llamada a la API con gestión integral de errores."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# No reintentar — la clave no es válida
raise RuntimeError("Clave de API inválida. Comprueba OPENAI_API_KEY.")
except BadRequestError as e:
# No reintentar — la solicitud está mal formada
raise RuntimeError(f"Solicitud inválida: {e.message}")
except RateLimitError:
# Reintentar con retroceso exponencial
delay = 2 ** attempt
print(f"Límite de tasa alcanzado. Esperando {delay}s...")
time.sleep(delay)
except InternalServerError:
# Reintentar — error del servidor
delay = 2 ** attempt
print(f"Error del servidor. Intento {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Reintentar — problema de red
delay = 2 ** attempt
print(f"Error de conexión. Intento {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Fallo tras {max_retries} intentos")
# Uso
try:
result = robust_api_call("¡Hola!")
print(result)
except RuntimeError as e:
print(f"Error fatal: {e}")
Errores específicos de la Responses API
Dos situaciones merecen un tratamiento separado porque aparecen bajo un código genérico pero requieren una corrección muy específica.
Contexto demasiado largo
Un prompt que excede la ventana de contexto devuelve un 400, igual que un error tipográfico en un parámetro. Para distinguir entre ambos, inspecciona el mensaje: la presencia de context_length_exceeded te señala hacia el truncamiento del texto o el cambio a un modelo con una ventana de contexto mayor, en lugar de revisar tus parámetros.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Excede la ventana de contexto
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("El prompt es demasiado largo para este modelo.")
print("Soluciones: truncar el texto o cambiar a un modelo")
print("con una ventana de contexto mayor.")
Modelo no disponible
Los identificadores de modelo no son eternos. Un despliegue que aún hace referencia a un modelo retirado falla con un 404, provocando que toda la aplicación se caiga aunque funcionara el día anterior. Gestiona este caso explícitamente: es un recordatorio automático para actualizar tu configuración.
try:
response = client.responses.create(
model="gpt-4-turbo", # retirado de la API el 23 de octubre de 2026
input="Test"
)
except NotFoundError as e:
print(f"Modelo no encontrado: {e.message}")
print("Usa gpt-5.6-sol, el sustituto indicado por OpenAI, o un modelo más nuevo.")
Registro estructurado de errores
Un error no registrado es un error que descubrirás mediante un ticket de cliente. Registrar en JSON en lugar de texto libre lo cambia todo cuando necesitas agregar: puedes contar los 429 por hora, filtrar por response_id o rastrear la desviación del consumo, algo imposible con líneas de registro escritas a mano.
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:
"""Llamada a la API con registro estructurado."""
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("¡Hola!")
Tabla resumen
Ten esta cuadrícula a mano: resume la decisión que debes tomar para cada código.
| Código | Excepción | ¿Reintentar? | Acción |
|---|---|---|---|
| 400 | BadRequestError | No | Corregir la solicitud |
| 401 | AuthenticationError | No | Verificar clave de API |
| 403 | PermissionDeniedError | No | Verificar permisos |
| 404 | NotFoundError | No | Verificar modelo/punto final |
| 422 | UnprocessableEntityError | No | Corregir el formato |
| 429 | RateLimitError | Sí | Retroceso exponencial |
| 500 | InternalServerError | Sí | Esperar y reintentar |
| 503 | InternalServerError | Sí | Servicio no disponible temporalmente |
Puntos clave
- Categoriza los errores: reintentables (429, 500, 503) frente a fatales (400, 401, 403)
- Usa retroceso exponencial para errores reintentables
- Nunca reintentes errores de autenticación o de solicitud inválida
- Registra cada error con contexto (código, mensaje, marca de tiempo)
- El SDK gestiona automáticamente 2 reintentos; configura
max_retriessi es necesario