Qué error es y qué hacer, reintentar, corregir o desviar

Un worker reintenta cinco veces cada falla, sin mirar cuál es. La auditoría encuentra miles de reintentos que nunca podían salir bien y un panel que dice “100% de éxito” mientras se guardan respuestas cortadas. Antes de elegir una estrategia de recuperación (recovery strategy), hay que saber qué tipo de error tenés adelante.

La pregunta que hay que hacerse

¿Si mando exactamente lo mismo dentro de un rato, puede salir bien? Si la respuesta es sí, es un error transitorio (transient error) y se reintenta. Si es no, reintentar solo gasta tiempo y cuota: hay que corregir el pedido o mandarlo por otro camino.

Errores HTTP

Código y tipo	Qué significa	Qué hacer
429 rate_limit_error	Pasaste un límite de tasa	Reintentar con espera exponencial (exponential backoff) y jitter, respetando retry-after
500 api_error	Error interno de Anthropic	Reintentar con backoff
529 overloaded_error	La API está sobrecargada	Reintentar con backoff
504 timeout_error	El pedido tardó demasiado	Pasar a streaming o a lotes para pedidos largos
400 invalid_request_error	El pedido está mal armado o usa algo que el modelo no acepta	Leer el mensaje y corregir; nunca reintentar igual
401 / 403	Clave inválida o sin permiso	Revisar credenciales y permisos
413 request_too_large	El pedido es demasiado grande	Achicar la entrada o usar otra vía (por ejemplo, archivos)

El SDK oficial ya reintenta los errores de conexión, los 429 y los 5xx con backoff (dos veces por defecto). Si encima envolvés cada llamada en tu propio bucle de cinco reintentos, multiplicás la carga justo cuando la API está saturada.

Un 400 que aparece después de cambiar el ID del modelo suele ser un cambio que rompe entre versiones, como el prellenado del mensaje del asistente que los modelos nuevos ya no aceptan. El mensaje del error lo dice.

Lo que llega con HTTP 200

Acá está la trampa: varios problemas no son errores HTTP. Hay que mirar el motivo de corte (stop_reason) de cada respuesta.

• max_tokens: la respuesta llegó al límite configurado y quedó cortada. Si output_tokens coincide con el límite, subí max_tokens para esa función y no muestres el texto como completo. Cambiar a un modelo más grande no lo arregla.
• refusal: el modelo se negó. Llega como 200, así que un panel que cuenta códigos HTTP nunca lo ve. Esos casos van a otro camino: reformular, un modelo de respaldo o revisión humana.
• Con streaming, un error puede llegar como evento error dentro del stream, después de que la API ya respondió 200. Si no hay message_stop, la respuesta está incompleta: se descarta y se reintenta con backoff.

Las trampas típicas

• Reintentar un 400, 401 o 403 “por si acaso”.
• Reintentar sin backoff, o todos los clientes a la vez, sin jitter.
• Ignorar retry-after.
• Guardar como éxito todo lo que vino con 200 sin mirar stop_reason.
• Cambiar de modelo o de prompt antes de leer qué error es.

En el examen

Leé el código, el tipo de error y el stop_reason que da el escenario: casi siempre está ahí la pista. Si la pregunta pide cuáles reintentar, elegí los transitorios (429, 500, 529) y descartá los que describen un problema del pedido o de las credenciales. Si todo devuelve 200 pero los resultados están mal, buscá la opción que ramifica por stop_reason.