Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
La API sigue un formato predecible de códigos de error HTTP:
400 - invalid_request_error: Hubo un problema con el formato o el contenido de tu solicitud. Este tipo de error también puede usarse para otros códigos de estado 4XX no listados en esta sección.
401 - authentication_error: Hay un problema con tu clave de API (por ejemplo, está mal formada, revocada o expirada; consulta Expiración de claves). En Claude Platform en AWS, esto también puede indicar un problema con tus credenciales de AWS o tu firma SigV4.
402 - billing_error: Hay un problema con tu información de facturación o pago. Verifica tus datos de pago en la Claude Console, o en AWS Marketplace si estás usando Claude Platform en AWS.
403 - permission_error: Tu clave de API no tiene permiso para usar el recurso especificado. Verifica el acceso de tu organización y la configuración del workspace en la Claude Console.
404 - not_found_error: No se encontró el recurso solicitado. Verifica la ruta del endpoint y cualquier ID de recurso en la URL de la solicitud.
409 - conflict_error: La solicitud entra en conflicto con el estado actual de un recurso. Por ejemplo, el recurso fue modificado de forma concurrente, o un valor que debe ser único ya está en uso. Resuelve el conflicto y luego reintenta la solicitud.
413 - request_too_large: La solicitud excede el número máximo permitido de bytes. Consulta Límites de tamaño de solicitud para conocer los máximos por endpoint.
429 - rate_limit_error: Tu cuenta ha alcanzado un "rate limit" (límite de velocidad).
500 - api_error: Ha ocurrido un error inesperado interno en los sistemas de Anthropic. Reintenta la solicitud con retroceso exponencial; si el error persiste, contacta a soporte con el ID de solicitud.
504 - timeout_error: La solicitud agotó el tiempo de espera durante el procesamiento. Considera usar la API de Messages con streaming para solicitudes de larga duración. Consulta Solicitudes largas para más opciones.
529 - overloaded_error: La API está temporalmente sobrecargada.
Los errores 529 pueden ocurrir cuando la API experimenta un tráfico alto entre todos los usuarios.
En casos raros, si tu organización tiene un aumento brusco en el uso, podrías ver errores 429 debido a los límites de aceleración de la API. Para evitar alcanzar los límites de aceleración, incrementa tu tráfico gradualmente y mantén patrones de uso consistentes.
Los SDKs oficiales reintentan automáticamente los fallos transitorios (como errores de conexión, límites de velocidad y errores de servidor 5xx) con retroceso exponencial, dos veces por defecto, respetando el encabezado retry-after cuando está presente. Cada cliente del SDK acepta una opción de máximo de reintentos para configurar o deshabilitar este comportamiento.
Al recibir una respuesta de streaming a través de eventos enviados por el servidor (SSE), puede ocurrir un error después de que la API devuelva una respuesta 200. En ese caso, el manejo de errores no sigue estos mecanismos estándar. Consulta Eventos de error para conocer la forma de los errores a mitad del stream.
La API aplica límites de tamaño de solicitud:
| Tipo de endpoint | Tamaño máximo de solicitud |
|---|---|
| API de Messages | 32 MB |
| API de Token Counting | 32 MB |
| API de Batch | 256 MB |
| API de Files | 500 MB |
Si excedes estos límites, recibirás un error 413 request_too_large. En la API de Claude directa, Cloudflare devuelve este error antes de que la solicitud llegue a los servidores de la API.
La API siempre devuelve los errores como JSON, con un objeto error de nivel superior que siempre incluye un valor type y message. La respuesta también incluye un campo request_id para facilitar el seguimiento y la depuración. Por ejemplo:
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}De acuerdo con la política de versionado, los valores dentro de estos objetos pueden expandirse, y es posible que los valores de type crezcan con el tiempo.
Los SDKs oficiales lanzan excepciones tipadas para estos errores en lugar de devolver JSON sin procesar, y los nombres de clase y los espacios de nombres difieren según el lenguaje. Por ejemplo, un 404 aparece como anthropic.NotFoundError en Python, Anthropic::Errors::NotFoundError en Ruby, com.anthropic.errors.NotFoundException en Java, y como un único valor *anthropic.Error (ramifica según StatusCode) en Go. Captura las clases tipadas del SDK en lugar de hacer coincidencias de cadenas con los mensajes de error, manejando primero las clases más específicas. Cada página del SDK documenta su jerarquía completa de excepciones:
Cada respuesta de la API incluye un encabezado request-id único. Este encabezado contiene un valor como req_018EeWyXxfu5pfWkrYcMdjWG. El mismo identificador aparece como el campo request_id en los cuerpos de respuesta de error. Al contactar a soporte sobre una solicitud específica, incluye este ID para ayudar a resolver tu problema rápidamente.
En Claude Platform en AWS, las respuestas incluyen dos IDs de solicitud: el ID de solicitud de AWS (x-amzn-requestid, primario, indexado en CloudTrail) y el ID de solicitud de Anthropic (request-id, secundario). Usa el ID de solicitud de AWS para búsquedas en CloudTrail y el ID de solicitud de Anthropic para tickets de soporte de Anthropic.
Los SDKs de Python y TypeScript exponen el ID de solicitud como una propiedad _request_id en los objetos de respuesta de nivel superior. Los SDKs de C#, Go, Java y PHP lo exponen a través de sus accesores de respuesta sin procesar, que también te permiten leer cualquier otro encabezado de respuesta. En Claude Platform en AWS, usa el accesor de respuesta sin procesar para leer también el ID de solicitud de AWS (x-amzn-requestid):
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")Para ejemplos de ID de solicitud de Claude Platform en AWS en otros lenguajes, consulta IDs de solicitud.
Considera usar la API de Messages con streaming o la API de Message Batches para solicitudes de larga duración, especialmente aquellas de más de 10 minutos.
Evita establecer un valor grande de max_tokens sin usar la API de Messages con streaming
o la API de Message Batches:
Si estás construyendo una integración directa con la API, configurar un TCP socket keep-alive puede reducir el impacto de los tiempos de espera de conexiones inactivas en algunas redes.
Los SDKs validan que no se espere que tus solicitudes a la API de Messages sin streaming excedan un tiempo de espera de 10 minutos. También establecen una opción de socket para TCP keep-alive.
Si no necesitas procesar eventos de forma incremental, los SDKs pueden consumir el stream por ti y devolver el objeto Message completo, idéntico al que devuelve una llamada sin streaming:
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "Write a detailed analysis..."}],
model="claude-sonnet-5",
) as stream:
message = stream.get_final_message()
print(next(block.text for block in message.content if block.type == "text"))Consulta Streaming de Messages para más detalles.
Los modelos Claude 4.6 y posteriores y Claude Mythos Preview no admiten el prellenado de mensajes del asistente. Enviar una solicitud con un último mensaje del asistente prellenado a cualquiera de estos modelos devuelve un error 400 invalid_request_error:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "This model does not support assistant message prefill. The conversation must end with a user message."
}
}Usa en su lugar salidas estructuradas en los modelos que lo admiten, instrucciones en la indicación del sistema, o output_config.format.
Si el mensaje del asistente más reciente contiene bloques thinking o redacted_thinking que fueron editados, reordenados, filtrados o reconstruidos antes de enviarse de vuelta a la API, la solicitud devuelve un error 400 invalid_request_error. El mensaje de error comienza con la posición del bloque problemático (por ejemplo, messages.1.content.0) y contiene:
`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.Con el uso de herramientas, cada bloque thinking y redacted_thinking del turno del asistente debe pasarse de vuelta exactamente como se recibió, incluidos los bloques cuyo campo thinking está vacío. Pasa los bloques de pensamiento de vuelta sin cambios, y si tu aplicación filtra los bloques de contenido por tipo antes de reenviarlos, incluye tanto thinking como redacted_thinking. Consulta Solución de problemas de pensamiento, Preservación de bloques de pensamiento y Salida de pensamiento en Claude Fable 5 y Claude Mythos 5.
Los modelos Claude 4.7 y posteriores han eliminado el "extended thinking" (pensamiento extendido). Enviar thinking: {"type": "enabled"} a cualquiera de estos modelos devuelve un error 400 invalid_request_error:
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.Usa en su lugar el pensamiento adaptativo. Migración al pensamiento adaptativo muestra el mapeo de parámetros, y Solución de problemas de pensamiento cubre la solución a partir del síntoma.
Los modelos que solo admiten pensamiento extendido (Claude 4.5 y modelos anteriores) rechazan thinking: {"type": "adaptive"} con un error 400 invalid_request_error:
adaptive thinking is not supported on this modelUsa thinking: {"type": "enabled", "budget_tokens": N} en estos modelos; consulta Pensamiento extendido para la configuración y Solución de problemas de pensamiento para la solución a partir del síntoma.
En Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview, el pensamiento siempre está activado. Enviar thinking: {"type": "disabled"} a cualquiera de estos modelos devuelve un error 400 invalid_request_error:
"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.En Claude Fable 5 y Claude Mythos 5, la propia sugerencia del mensaje de error de "thinking.type.enabled" también es rechazada. Omite el parámetro thinking y la solicitud se ejecutará con pensamiento adaptativo. Para mantener el contenido de pensamiento fuera de las respuestas sin desactivar el pensamiento, establece display: "omitted" en la configuración de pensamiento. Consulta Solución de problemas de pensamiento.
Si cada solicitud a Claude Platform en AWS devuelve "Outbound web identity federation is disabled for your account", ejecuta aws iam enable-outbound-web-identity-federation una vez por cuenta de AWS. Consulta Habilitar la federación de identidad web saliente para más detalles.
Inicia una sesión de rutina de Claude Code bajo demanda enviando una solicitud POST autenticada.
Para mitigar el uso indebido y gestionar la capacidad de la API, existen límites sobre cuánto puede usar una organización la API de Claude.
Transmite las respuestas de la API de Messages de forma incremental con eventos enviados por el servidor, incluyendo deltas de texto, uso de herramientas y pensamiento extendido.
Was this page helpful?