Prácticas recomendadas fundamentales de la API de Claude

Veinticinco prácticas para una autenticación, solicitudes y manejo de errores fiables al crear sobre la API de Claude con el SDK oficial de Python.

Organizado desde la configuración y autenticación hasta el diseño de solicitudes, el manejo de errores y la selección de modelos.

Cómo usar esta lista

• Trate la sección A como higiene de configuración no negociable antes de escribir cualquier código de aplicación.
• Vuelva a visitar la sección C cada vez que aparezca un nuevo modo de fallo en los registros de producción.
• Utilice la sección D cuando elija un modelo por primera vez, y de nuevo cada vez que el coste o la latencia se conviertan en una preocupación.

A - Autenticación y Configuración

• Nunca codifique su clave de API en el código fuente. Utilice la variable de entorno ANTHROPIC_API_KEY o un gestor de secretos, y añada .env a .gitignore antes de su primer commit.
• Falle rápidamente cuando falte la clave de API. Compruebe explícitamente la clave al inicio y genere un error claro, en lugar de dejar que un 401 críptico aparezca profundamente en su pila de llamadas más tarde.
• Utilice claves de API separadas por entorno. Las claves de desarrollo, staging y producción le permiten revocar o rotar una sin afectar a las demás.
• Fije la versión del SDK de Anthropic en su archivo de dependencias. Una dependencia no fijada puede introducir cambios que rompan en una instalación nueva; actualice deliberadamente en su lugar.
• Construya el cliente una vez y reutilícelo. Cree anthropic.Anthropic() al inicio de la aplicación o al cargar el módulo, no por solicitud o por llamada a función.

B - Diseño de Solicitudes

• Establezca siempre max_tokens deliberadamente, no a un valor predeterminado arbitrario. Demasiado bajo trunca la salida útil; demasiado alto desperdicia presupuesto en tareas que no lo necesitan.
• Utilice las indicaciones del sistema para instrucciones persistentes, no para el primer mensaje del usuario. Mantener las instrucciones de rol/restricción en system mantiene el historial de messages centrado en la conversación real.
• Reduzca la temperatura para tareas fácticas, estructuradas o deterministas. Reserve valores más altos para la generación verdaderamente creativa o exploratoria.
• Vuelva a enviar el historial completo de la conversación en cada llamada. La API no tiene estado; no hay sesión en el lado del servidor a la que hacer referencia, por lo que el cliente es el propietario del estado de la conversación.
• Prefiera la temperatura sobre top_p para la mayoría de los ajustes. Ajuste una perilla deliberadamente en lugar de cambiar tanto temperature como top_p a la vez, lo que hace que el comportamiento sea más difícil de predecir.
• Mantenga las indicaciones y las instrucciones del sistema en el control de versiones. Trate el texto de las indicaciones como código, revise los cambios en él de la misma manera que revisaría los cambios de lógica.

C - Manejo de Errores y Resiliencia

• Establezca un max_retries sensato en el cliente. El backoff exponencial integrado del SDK maneja 429/5xx automáticamente; no lo deshabilite sin una razón específica.
• Capture tipos de excepción específicos, no un Exception genérico. anthropic.AuthenticationError, anthropic.RateLimitError y anthropic.BadRequestError apuntan a una corrección diferente.
• Nunca reintente errores 4xx que no sean 429. Una solicitud mal formada falla de manera idéntica en cada reintento; corrija la solicitud en lugar de reintentarla.
• Añada jitter a cualquier lógica de reintento personalizada. Sin varianza aleatoria, muchos clientes que se retiran con el mismo horario pueden resincronizarse y volver a activar el mismo límite de velocidad.
• Establezca un tiempo de espera de solicitud apropiado para su caso de uso. Las generaciones de streaming largas necesitan un tiempo de espera más largo que las compleciones cortas y simples.
• Registre los códigos de estado y los mensajes de error, pero redacte las cabeceras de la solicitud. Los volcados completos de la solicitud pueden filtrar su clave de API en los registros si no se limpian primero.
• Supervise usage.input_tokens y usage.output_tokens con tráfico real. Los recuentos de tokens impulsan tanto el coste como el uso de la ventana de contexto; no vuele a ciegas en ninguno de los dos.

D - Selección de Modelos y Coste

• Utilice Claude Sonnet 5 por defecto a menos que tenga una razón específica para cambiarlo. Es el valor predeterminado equilibrado actual en toda la línea.
• Enrute tareas simples y de alto volumen a Claude Haiku 4.5. La clasificación, el etiquetado y la extracción corta rara vez necesitan un modelo insignia.
• Reserve Claude Opus 4.8 o Claude Fable 5 para tareas genuinamente difíciles y de varios pasos. Usar un modelo insignia en todas partes infla el coste sin un beneficio de calidad correspondiente para el trabajo simple.
• Centralice las cadenas de ID de modelo como constantes con nombre. Un cambio futuro de modelo debería ser un cambio de una línea, no una búsqueda y reemplazo en toda la base de código.
• Verifique los ID de modelo y los precios actuales antes de codificarlos. Los nombres de los modelos, los límites de contexto y los precios cambian a medida que se envían nuevas versiones; no confíe en documentación o datos de entrenamiento obsoletos.
• Presupueste los precios posteriores a la introducción, no solo las tarifas de lanzamiento. Algunos modelos se lanzan con un precio introductorio de tiempo limitado que aumenta en una fecha anunciada; planifique en torno a la tarifa estable.

E - Arquitectura y Mantenibilidad

• Envuelva el cliente SDK una vez que su base de código tenga múltiples puntos de llamada. Un envoltorio delgado centraliza el modelo predeterminado, los reintentos, el tiempo de espera y el manejo de errores en lugar de repetirlos en todas partes.
• Mantenga el uso de clientes síncronos y asíncronos separado. Utilice anthropic.AsyncAnthropic dentro del código asyncio y anthropic.Anthropic en código síncrono; no los mezcle en una sola ruta de llamada.

Preguntas frecuentes

Relacionado

• Entendiendo el Ciclo de Vida de las Solicitudes de la API de Claude - el flujo de solicitudes que protegen estas prácticas.
• Manejo de Límites de Tasa con Backoff Exponencial - las prácticas de reintento en la sección C, en profundidad.
• Referencia de Códigos de Error y Solución de Problemas de la API de Claude - el catálogo completo de errores detrás de la sección C.
• Selección de un Modelo: Claude Fable 5, Opus 4.8, Sonnet 5 y Haiku 4.5 - la comparación detrás de la sección D.
• Construcción de un Envoltorio de Cliente de API de Claude Reutilizable - el patrón detrás de la sección E.

Versiones de la 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, las versiones del SDK y los precios cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.