Gestión de errores y límites de velocidad
Gestionará errores habituales de la API, incluidas las excepciones por límites de velocidad, los errores de autenticación y los tiempos de espera, mediante lógica de reintentos y patrones de espera exponencial.
Gestión de errores y límites de velocidad es una lección gratuita de AI Engineering Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Engineering Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Engineering Academy incluye 4 lecciones en total.
Por qué se producen errores de la API
Muchas cosas pueden salir mal en una llamada a la API: sobrecarga, cuota insuficiente, pérdida de conexión o una solicitud incorrecta. Tratar las llamadas como infalibles garantiza un código frágil; conozca primero los tipos de error.
Resumen de los tipos de error de OpenAI
El SDK genera excepciones específicas, como RateLimitError y AuthenticationError. Solo merece la pena reintentar las transitorias, como los límites de solicitudes y las pérdidas de red; las demás no se resolverán por sí solas.
Captura de errores con Try-Except
Envuelva cada llamada en try-except y capture excepciones específicas, no un except sin especificar. Así podrá responder adecuadamente a cada fallo en lugar de ocultar errores. El código muestra cómo hacerlo.
import openai
client = openai.OpenAI()
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(response.choices[0].message.content)
except openai.AuthenticationError as e:
print('Bad API key. Check OPENAI_API_KEY environment variable.')
raise # do not retry
except openai.RateLimitError as e:
print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
print('Network error:', e)
except openai.APIStatusError as e:
print('Server error', e.status_code, e.message)Comprensión de los límites de solicitudes
OpenAI aplica dos límites de solicitudes a la vez: solicitudes por minuto (RPM) y tokens por minuto (TPM). Un prompt enorme puede agotar el TPM en una sola solicitud. Ambos devuelven un 429.
Espera exponencial: la estrategia de reintento adecuada
¿Ha alcanzado un límite de solicitudes? Espere y vuelva a intentarlo mediante una espera exponencial: 1 s, 2 s, 4 s, duplicando el tiempo cada vez. Añada un poco de jitter y un número máximo de reintentos para no entrar nunca en un bucle infinito. Consulte el código.
import time
import random
import openai
client = openai.OpenAI()
def call_with_backoff(messages, max_retries=5):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model='gpt-4o-mini',
messages=messages
)
except openai.RateLimitError:
if attempt == max_retries - 1:
raise
wait = (2 ** attempt) + random.uniform(0, 1)
print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
time.sleep(wait)
except (openai.APIConnectionError, openai.APIStatusError):
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)Uso de la biblioteca tenacity
No implemente los reintentos manualmente: la biblioteca tenacity lo hace de forma limpia. Decore su función con @retry y gestionará por usted la espera exponencial, el jitter y las condiciones de reintento.
from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai
client = openai.OpenAI()
@retry(
wait=wait_random_exponential(min=1, max=60),
stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
return client.chat.completions.create(**kwargs)
response = completion_with_backoff(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)Configuración del tiempo de espera
Una solicitud bloqueada puede congelar su aplicación indefinidamente, por lo que debe establecer siempre un timeout. El SDK acepta un tiempo de espera en segundos, ya sea en el cliente o en cada llamada. Elija un valor adecuado para la longitud de respuesta esperada.
import openai
# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)
# Or override per request
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
timeout=60.0
)
except openai.APITimeoutError:
print('Request timed out. Try a shorter prompt or increase timeout.')Gestión de errores de autenticación
Un AuthenticationError (401) significa que su clave es incorrecta, ha caducado o se ha revocado; reintentarlo nunca ayuda. Registre el error, genere una alerta y falle rápidamente en lugar de consumir su límite de reintentos.
import os
import openai
api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
raise EnvironmentError(
'OPENAI_API_KEY not set. Export it before running.'
)
client = openai.OpenAI(api_key=api_key)
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello'}]
)
except openai.AuthenticationError:
# Do NOT retry - the key itself is invalid
raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')Cuota frente a límites de solicitudes
Ambos errores parecen RateLimitError, pero son diferentes: los límites de solicitudes son restricciones por minuto que se restablecen por sí solas, mientras que los límites de cuota son topes de gasto que requieren más créditos.
Registro de errores para la depuración
En producción, registre todos los errores con contexto: el tipo, el modelo, los parámetros, el recuento de tokens, la hora y el ID de solicitud. Ese ID de solicitud es exactamente lo que necesita el servicio de asistencia de OpenAI. Consulte el código.
import logging
import openai
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
client = openai.OpenAI()
def safe_completion(model, messages):
try:
response = client.chat.completions.create(
model=model, messages=messages
)
return response
except openai.RateLimitError as e:
logger.warning(
'Rate limit hit',
extra={'model': model, 'error': str(e)}
)
raise
except openai.APIStatusError as e:
logger.error(
'API server error',
extra={
'status_code': e.status_code,
'request_id': e.request_id,
'model': model
}
)
raiseGestión de errores en aplicaciones de producción
Una estrategia sólida para producción consiste en fallar rápidamente ante errores irrecuperables, reintentar los transitorios con espera exponencial y ofrecer alternativas adecuadas. No permita nunca que un error de la API derribe todo su servidor.
Comprobación rápida
Compruebe su comprensión de los conceptos de Ingeniería de IA de esta lección.
Resumen de la lección
Ha aprendido a gestionar los fallos: OpenAI genera excepciones específicas, los límites de solicitudes requieren espera exponencial con jitter y los errores de autenticación deben provocar un fallo rápido. A continuación: escritura de prompts eficaces.
Aprende Python con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 30
- Lecciones
- 120
Preguntas frecuentes
¿La lección «Gestión de errores y límites de velocidad» es gratis?
Sí — el texto completo de «Gestión de errores y límites de velocidad» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Engineering Academy, actualiza a CoddyKit PRO. El curso de AI Engineering Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Gestión de errores y límites de velocidad»?
Gestionará errores habituales de la API, incluidas las excepciones por límites de velocidad, los errores de autenticación y los tiempos de espera, mediante lógica de reintentos y patrones de espera e… Practicas AI Engineering Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar AI Engineering Academy?
No se requiere experiencia previa. AI Engineering Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Gestión de errores y límites de velocidad»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de AI Engineering Academy?
Sí. Cada lección de AI Engineering Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Configuración del entorno de Python
- El endpoint de Chat Completions
- Control del comportamiento del modelo con parámetros
- Gestión de errores y límites de velocidad