Tipos de Excepción del SDK de Python de un Vistazo
Una referencia densa para cada clase de excepción que el SDK de Python anthropic genera, y si cada una es segura para reintentar.
Cómo Usar esta Hoja de Referencia
- Busca la excepción que capturaste (o quieres capturar) en la tabla principal para su estado HTTP y seguridad de reintento.
- Usa la sección "Orden de captura" al escribir una cadena
except- la más específica primero. - Usa la tabla "Qué reintenta ya el SDK" antes de añadir tu propia lógica de reintento encima de los reintentos integrados del SDK.
Clases de Excepción de un Vistazo
| Excepción | Estado HTTP | ¿Seguro para reintentar? | Causa Típica |
|---|---|---|---|
BadRequestError | 400 | No | Solicitud mal formada, valor de parámetro inválido |
AuthenticationError | 401 | No | Clave API faltante o inválida |
PermissionDeniedError | 403 | No | La clave API carece de acceso al modelo o función solicitada |
NotFoundError | 404 | No | ID de modelo o endpoint inválido |
UnprocessableEntityError | 422 | No | La solicitud es JSON bien formado pero semánticamente inválido |
RateLimitError | 429 | Sí (ya se reintentó automáticamente) | Se excedieron las solicitudes por minuto, tokens por minuto o tokens por día |
InternalServerError | 5xx | Sí (ya se reintentó automáticamente) | Problema transitorio del servicio de Anthropic |
APIConnectionError | (sin respuesta) | Sí (ya se reintentó automáticamente) | Fallo de DNS, conexión rechazada, interrupción de red antes de cualquier respuesta |
APIStatusError | cualquier no-2xx | Depende - clase base | Captura general para cualquier error HTTP no coincidente con una subclase más específica arriba |
APIError | (cualquiera) | Depende - clase base | Raíz de toda la jerarquía de excepciones; la captura más amplia posible |
Orden de Captura (Más Específico Primero)
import anthropic
try:
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
except anthropic.NotFoundError:
# ID de modelo o endpoint incorrecto - corrige la solicitud, no reintentes
...
except anthropic.RateLimitError:
# Se agotaron los reintentos propios del SDK; espera más o reduce la tasa de solicitudes
...
except anthropic.APIStatusError as e:
# Cualquier otra respuesta HTTP no-2xx
print(e.status_code, e.message)
except anthropic.APIConnectionError:
# Fallo de red antes de recibir cualquier respuesta
...APIConnectionError es un hermano de APIStatusError en Python (no una subclase), por lo que necesita su propia cláusula except; no será capturado por una rama except anthropic.APIStatusError.
Qué Reintenta Automáticamente el SDK
| Fallo | ¿Reintentado automáticamente por defecto? | Tu código necesita... |
|---|---|---|
APIConnectionError (fallo de red) | Sí, hasta max_retries (por defecto 2) | Manejar solo si se agotan los reintentos |
429 (RateLimitError) | Sí, respetando retry-after | Manejar solo si se agotan los reintentos; considera una espera más larga |
5xx (InternalServerError) | Sí | Manejar solo si se agotan los reintentos |
408, 409 | Sí | Manejar solo si se agotan los reintentos |
400, 401, 403, 404, 422 | No | Corregir la solicitud o las credenciales; reintentar sin cambios falla de nuevo |
Estrategias de Manejo Seguras para Reintentos
| Excepción | Estrategia Recomendada |
|---|---|
RateLimitError (después de agotar reintentos) | Espera significativamente más que la ventana de reintento por defecto del SDK, o reduce la carga; considera un limitador de tasa de cubo de tokens en el lado del cliente |
APIConnectionError (después de agotar reintentos) | Muestra un estado de "servicio no alcanzable" al usuario; verifica tu propia red/DNS antes de asumir que Anthropic está caído |
InternalServerError (después de agotar reintentos) | Verifica status.anthropic.com; si es persistente, trátalo como una interrupción en lugar de un error de código |
AuthenticationError | Nunca reintentes; verifica que ANTHROPIC_API_KEY esté configurada y sea válida, luego falla ruidosamente - un bucle de reintento silencioso contra una clave incorrecta solo desperdicia tiempo |
BadRequestError | Nunca reintentes sin cambios; registra la carga útil de la solicitud (redactando secretos) y corrige el campo mal formado |
PermissionDeniedError | Nunca reintentes; la clave API necesita permisos diferentes o una concesión de acceso a modelo diferente |
NotFoundError | Nunca reintentes; casi siempre es un ID de modelo mal escrito - verifica contra el catálogo de modelos actual |
Uso de .type para Clasificación Más Detallada
Cada subclase de APIStatusError expone una cadena .type que coincide con la propia taxonomía de errores de la API, útil cuando un único estado HTTP cubre más de una causa subyacente:
except anthropic.APIStatusError as e:
if e.type == "rate_limit_error":
...
elif e.type == "overloaded_error":
...
elif e.type == "invalid_request_error":
...Preguntas Frecuentes
¿Necesito escribir mi propio bucle de reintento para RateLimitError?
No para el caso común.
El SDK ya reintenta los 429 automáticamente hasta max_retries veces con espera; escribe tu propio manejo solo para lo que sucede después de que se agotan los reintentos.
¿Por qué APIConnectionError no es una subclase de APIStatusError?
Porque representa un fallo que ocurrió antes de que se recibiera cualquier respuesta HTTP (un error de red), mientras que APIStatusError y sus subclases representan una respuesta que llegó con un estado no-2xx. Necesitan cláusulas except separadas.
¿Cuál es la diferencia entre capturar APIStatusError y APIError?
APIError es la raíz de toda la jerarquía, incluyendo APIConnectionError. APIStatusError solo cubre las respuestas que realmente te llegaron con un código de estado HTTP. Capturar APIStatusError específicamente excluye los fallos a nivel de conexión.
¿Debería reintentarse AuthenticationError alguna vez?
No.
Una clave API incorrecta o faltante no se vuelve válida al reintentar; corrige la credencial y falla rápido en lugar de entrar en un bucle.
¿Qué significa UnprocessableEntityError en la práctica?
La solicitud era JSON válido con la forma correcta, pero la API rechazó su contenido por una razón semántica; por ejemplo, un valor budget_tokens que no satisface las restricciones de la API para ese campo.
¿Cómo distingo rate_limit_error de overloaded_error si ambos podrían aparecer como excepciones diferentes?
RateLimitError se mapea específicamente a HTTP 429, mientras que overloaded_error (un 529) generalmente se captura como APIStatusError; verifica e.type == "overloaded_error" dentro de esa rama para distinguirlo.
¿Cuál es el error más común al capturar estas excepciones?
Escribir un único y amplio except anthropic.APIError: (o capturar Exception simple) que trata cada fallo de manera idéntica, perdiendo la distinción entre errores reintentables y no reintentables. Captura la clase más específica que te interese primero.
¿El cliente async (AsyncAnthropic) genera los mismos tipos de excepción?
Sí.
La jerarquía de excepciones es idéntica entre Anthropic() y AsyncAnthropic() - solo la convención de llamada (await) difiere.
¿Es un 404 siempre un ID de modelo incorrecto?
Es la causa más común, pero cualquier ruta de endpoint inválida (improbable si solo usas los métodos del SDK) también produciría un 404. Verifica primero la cadena exacta del ID del modelo contra el catálogo actual.
¿Qué debería registrar cuando capturo un APIStatusError?
Como mínimo, e.status_code, e.message y e.type. Evita registrar el cuerpo completo de la solicitud sin redactar si pudiera contener contenido sensible del usuario.
Relacionado
- Conceptos Básicos del SDK de Python - una primera mirada a la captura de excepciones tipificadas
- Referencia de Configuración de Reintentos y Tiempos de Espera del SDK de Python - qué reintenta
max_retriesantes de que estas excepciones aparezcan - El Modelo Mental del SDK de Python de Anthropic - cómo los reintentos y errores encajan en el diseño general del SDK
- Mejores Prácticas del SDK de Python - manejo de errores como parte de una lista de verificación más amplia
Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.