Prácticas recomendadas de solución de problemas y fiabilidad

Estas son las prácticas que separan a un equipo que trata cada fallo de la API de Claude como un misterio aislado de uno que reconoce patrones, soluciona las causas raíz y mejora su respuesta a incidentes con el tiempo.

Cómo usar esta lista

• Trata la categoría A como una base no negociable para cualquier integración de Claude en producción; las categorías B-E se basan en ella.
• Utiliza esto como una auditoría periódica, no solo como una lista de verificación de configuración única; revísala después de cualquier incidente para ver qué regla la habría detectado antes.
• Vincula las reglas aplicables (registro estructurado, clasificación de errores) a la revisión de código o CI siempre que sea posible, en lugar de depender de la memoria.
• Empareja esta lista con la plantilla de RCA cuando se viole una regla y cause un incidente; los elementos de acción de la RCA a menudo se mapean directamente a una de estas prácticas.

A - Fundamentos de observabilidad

• Registra cada llamada a la API de Claude con un ID de solicitud, latencia y resultado. Sin un ID de solicitud capturado tanto en los éxitos como en los fallos, a menudo no podrás obtener más detalles sobre un incidente pasado, ni de tus propios datos ni del soporte de Anthropic.
• Clasifica cada fallo en una familia de fallos (capacidad, contrato, ciclo de vida, coste/latencia) en el punto de captura. Etiquetar los fallos cuando ocurren, no después durante una RCA, es lo que hace que los paneles y las alertas sean realmente consultables.
• Realiza un seguimiento del uso de tokens por llamada, no solo por período de facturación. El registro de input_tokens/output_tokens por llamada es tu primera señal de crecimiento del contexto o de una tormenta de fallos en la caché, mucho antes de que la factura mensual te lo diga.
• Ejecuta una comprobación de estado independiente separada del tráfico real. Un ping programado de bajo coste confirma si un problema es externo (la API) o local (tu patrón de tráfico) cuando las tasas de error de los usuarios reales se disparan.
• Alerta sobre umbrales que se aproximan, no solo sobre fallos duros. Una advertencia al 80% de un límite de tasa o presupuesto de ventana de contexto te da tiempo para actuar antes de que ocurra un fallo que afecte al usuario.

B - Disciplina de capacidad y reintentos

• Lee las cabeceras de respuesta de límite de tasa, no adivines qué límite se alcanzó. anthropic-ratelimit-requests-remaining, -input-tokens-remaining y -output-tokens-remaining te dicen exactamente qué techo provocó un 429, lo que cambia la solución.
• Distingue el tráfico ráfaga de la sobrecarga sostenida antes de elegir una solución. Una mejora de capacidad no soluciona un patrón de ráfagas recurrente, y la retroalimentación por sí sola no soluciona el crecimiento sostenido real que supera tu nivel.
• Utiliza retroceso exponencial con jitter, nunca un intervalo de reintento fijo. Los intervalos fijos sincronizan los reintentos entre clientes y pueden recrear el pico exacto que causó el fallo original.
• Solo reintenta excepciones genuinamente transitorias. RateLimitError, errores de conexión/tiempo de espera y respuestas 5xx son reintentables; una solicitud mal formada 4xx fallará de manera idéntica cada vez, reintentarla solo añade ruido.
• Limita los intentos de reintento y añade un disyuntor para fallos sostenidos. Un bucle de reintento ilimitado puede convertir un fallo transitorio en una solicitud colgada indefinidamente; un disyuntor protege al llamador una vez que se sabe que una dependencia está caída.

C - Seguridad de contrato (Uso de herramientas)

• Valida cada entrada de uso de herramientas contra su esquema antes de ejecutar la herramienta. Nada garantiza estructuralmente que la llamada a la herramienta del modelo coincida con tu input_schema; valida incluso para herramientas que "siempre" reciben argumentos simples en la práctica.
• Registra el bloque de uso de herramientas sin procesar antes de intentar analizarlo o validarlo. Si la validación o la reparación fallan posteriormente, la entrada de registro sin procesar es la única evidencia que tendrás para diagnosticar lo que realmente sucedió.
• Devuelve resultados de herramientas estructurados con is_error en lugar de tragar silenciosamente los fallos de validación. Un error capturado silenciosamente parece un turno exitoso para el resto del bucle del agente, y el fallo real aparece más tarde, desconectado de su causa.
• Rechaza coincidencias ambiguas en lugar de adivinar un valor predeterminado. Repara solo casos no ambiguos y de bajo riesgo (normalización de mayúsculas/minúsculas); adivinar un valor para un campo requerido faltante corre el riesgo de ejecutar la herramienta con datos significativamente incorrectos.

D - Gestión del ciclo de vida (Contexto y streaming)

• Cuenta los tokens por turno y recorta en los límites de turno, no a mitad de mensaje. Truncar a mitad de mensaje puede dejar huérfano un bloque tool_use de su tool_result, que la API rechazará por completo.
• Reserva un margen real por debajo del límite de contexto duro. El 15-25% de la ventana, reservado para la propia respuesta del modelo y cualquier resultado de herramienta pendiente, evita que un turno falle justo en el borde.
• Persiste el historial completo de la conversación fuera del contexto de trabajo recortado. Recortar para la API nunca debe significar perder datos para tus propios registros o para una revisión humana posterior.
• Realiza un seguimiento de la salida parcial a medida que se transmite y decide de antemano si una reconexión reanuda o reinicia. La API no reanuda una transmisión interrumpida desde donde la dejó; una reconexión es siempre una nueva solicitud, así que decide el comportamiento antes de que ocurra la primera interrupción en producción, no durante el incidente.

E - Estabilidad de costes y caché

• Mantén los prefijos cacheados (prompts del sistema, definiciones de herramientas) completamente estáticos, con los datos volátiles movidos al mensaje del usuario. Un solo campo dinámico dentro de un bloque cacheado, una marca de tiempo, un ID de solicitud, garantiza un fallo en cada llamada.
• Construye definiciones de herramientas en un orden fijo y explícito. Ensamblar listas de herramientas a partir de un dict o set no ordenado puede reordenar silenciosamente el prefijo serializado entre implementaciones, rompiendo el hash de la caché sin ningún cambio de código en las herramientas mismas.
• Supervisa la tasa de aciertos de la caché como una métrica de primera clase, no como una ocurrencia tardía. Un fallo en la caché no produce ningún error, por lo que sin una monitorización dedicada, una tormenta de fallos es invisible hasta que alguien revisa la factura o el panel de latencia.
• Compara el prefijo serializado real, no solo la plantilla de origen, cuando la tasa de aciertos disminuye. Los valores interpolados pueden cambiar los bytes finales enviados, incluso cuando la plantilla en sí parece inalterada en una comparación.

F - Respuesta a incidentes

• Escribe una RCA para cualquier incidente que haya activado una alerta, haya incumplido un SLA o haya causado un pico de costes notable. Una resolución rápida sin RCA a menudo significa que la misma causa raíz resurge más tarde sin que nadie reconozca el patrón.
• Separa el evento desencadenante de la causa raíz en cada RCA. El desencadenante (un pico de tráfico, una implementación) a menudo es inevitable; la causa raíz (falta de retroceso, sin límite de concurrencia) es generalmente lo que realmente se puede solucionar.
• Asigna un propietario y una fecha objetivo a cada elemento de acción. Un elemento de acción sin ambos se convierte silenciosamente en un deseo en lugar de un compromiso.
• Almacena las RCA completadas de forma consultable por familia de fallos. Un patrón recurrente de fallos de capacidad o contrato en múltiples incidentes es una fuerte señal para invertir en la solución subyacente, no solo para parchear cada ocurrencia.

Cuando hayas terminado

Pasar cada elemento de las categorías A-C es la base para una integración de Claude en producción que falla con gracia en condiciones normales. Las categorías D-F son más importantes para cargas de trabajo agentivas, de múltiples turnos o de alto volumen, donde los fallos de ciclo de vida y coste se acumulan de maneras que una simple integración de chatbot rara vez ve.

Preguntas frecuentes

Relacionado

• Comprender por qué los agentes de Claude fallan en producción - la taxonomía de fallos en torno a la cual se organizan estas prácticas.
• Fundamentos de solución de problemas y fiabilidad - el punto de partida práctico sobre el que se basa la categoría A.
• Estrategias de reintento y retroceso exponencial para fallos transitorios de la API de Claude - el patrón completo detrás de las reglas de reintento de la categoría B.
• Manejo de JSON de uso de herramientas mal formados y fallos de validación de esquemas - el patrón completo detrás de la categoría C.
• Plantilla de Análisis de Causa Raíz para Fallos de Agentes - la plantilla a la que apuntan las reglas de respuesta a incidentes de la categoría F.

Versiones de pila: Escrito contra la línea de modelos de 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 los modelos, los precios y las versiones del SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.