Temario Lección 121 de 250 · Llamar a un LLM de verdad
Llamar a un LLM de verdad

Tratar los errores de la API

Las llamadas reales por la red fallan, y un cliente de LLM de producción vive o muere según cómo reaccione. El instinto más útil es separar los fallos en dos grupos: los que merece la pena reintentar (un tropiezo pasajero que probablemente se arregle solo) y los que tienes que arreglar en la petición (un fallo en tu llamada que ningún reintento va a solucionar). El código de estado HTTP te dice en qué grupo estás.

En el código real capturas las excepciones con tipo del SDK, que llevan cada una un .status_code (solo como ilustración -> no llamamos a la red):

import anthropic
try:
    resp = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  messages=history)
except anthropic.RateLimitError:          # HTTP 429 -> back off and retry
    ...
except anthropic.APIStatusError as e:     # any other 4xx/5xx, has e.status_code
    if should_retry(e.status_code):
        ...   # retry with backoff
    else:
        raise # 400/401/403/404 -> a bug in YOUR request, surface it

Los grupos, por código de estado:

  • Reintentar -> 408 (tiempo de espera de la petición agotado), 409 (conflicto), 429 (límite de frecuencia) y cualquier error del servidor de 500 a 599, como 502, 503 (no disponible) o 529 (sobrecargado). Son pasajeros: espera y vuelve a intentarlo. Cuando la respuesta lleva una cabecera retry-after, espera al menos ese tiempo.
  • Arreglar la petición -> 400 (petición incorrecta), 401 (clave de API incorrecta), 403 (prohibido), 404 (modelo o ruta equivocados). Reintentar una llamada mal formada solo quema cuota.
  • Desconocido -> cualquier otra cosa (incluido un éxito como 200): no des por hecho que es seguro reintentar.

Vas a construir dos funciones pequeñas. classify_error(status) devuelve el nombre del grupo: "retry", "fix-request" o "unknown". should_retry(status) devuelve el booleano -> True exactamente cuando el estado está en el conjunto de reintentos, y si no False.

Esta lección decide si reintentar; la espera entre intentos es una habilidad aparte. El módulo production-patterns trata el retroceso exponencial (doblar la espera en cada intento: 1 s, 2 s, 4 s...), y encima AÑADES jitter -> una pequeña cantidad aleatoria de espera extra -> para que una flota de clientes rechazados en el mismo instante no reintente toda al mismo compás y vuelva a arrollar el servidor (la "estampida"). Constrúyelo de forma que la tabla de estados dé varias respuestas distintas (429 -> retry, 400 -> fix-request, 200 -> unknown), lo que significa que ninguna constante puede pasar.

Tu turno

Escribe classify_error(status), que devuelve "retry" para 408 (tiempo de espera de la petición agotado), 409 (conflicto), 429 (límite de frecuencia) y todos los errores del servidor de 500 a 599 (529 significa sobrecargado), "fix-request" para {400, 401, 403, 404} y "unknown" para cualquier otra cosa. Escribe should_retry(status), que devuelve el booleano True exactamente cuando classify_error(status) es "retry", y si no False. (Es la misma regla que usa el SDK oficial de Anthropic: reintenta estos estados, y los errores de conexión, dos veces por defecto, y espera lo que pida una cabecera retry-after. En el código real casi siempre configuras max_retries en lugar de escribir esto tú; escribirlo una vez te enseña lo que hace.)

¿Has visto un problema en esta lección? Avísanos · Preguntar sobre esta lección

Este ejercicio se abre pronto

Termina la lección anterior y esta se desbloquea. Todo el curso es gratis, no hace falta cuenta, y puedes leer esta lección ahora mismo.