Errores



Errores HTTP

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. 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 detalles de pago en 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.

• 404 - not_found_error: No se encontró el recurso solicitado.

• 413 - request_too_large: La solicitud excede el número máximo permitido de bytes. Consulta Límites de tamaño de solicitud para ver los máximos por endpoint.

• 429 - rate_limit_error: Tu cuenta ha alcanzado un límite de velocidad.

• 500 - api_error: Ha ocurrido un error inesperado interno en los sistemas de Anthropic.

• 504 - timeout_error: Se agotó el tiempo de espera de la solicitud durante el procesamiento. Considera usar streaming para solicitudes de larga duración.

• 529 - overloaded_error: La API está temporalmente sobrecargada.

  

  Los errores 529 pueden ocurrir cuando las APIs experimentan un alto tráfico entre todos los usuarios.

  En casos excepcionales, si tu organización tiene un aumento repentino en el uso, podrías ver errores 429 debido a límites de aceleración en la API. Para evitar alcanzar los límites de aceleración, incrementa tu tráfico gradualmente y mantén patrones de uso consistentes.

Al recibir una respuesta de streaming a través de SSE, es posible que ocurra un error después de devolver una respuesta 200, en cuyo caso el manejo de errores no seguiría estos mecanismos estándar.



Límites de tamaño de solicitud

La API aplica límites de tamaño de solicitud para garantizar un rendimiento óptimo:

Si excedes estos límites, recibirás un error 413 request_too_large. En la API directa de Claude, este error es devuelto desde Cloudflare antes de que la solicitud llegue a los servidores de la API.



Estructura de los errores

Los errores siempre se devuelven 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 ampliarse, y es posible que los valores de type aumenten con el tiempo.



Tipos de error del SDK

Los SDKs oficiales lanzan excepciones tipadas para estos errores en lugar de devolver JSON sin procesar, y los nombres de clase y 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 coincidencia de cadenas con los mensajes de error, manejando primero las clases más específicas. Cada página de SDK documenta su jerarquía completa de excepciones:

• Python · TypeScript · C# · Go · Java · PHP · Ruby



ID de solicitud

Cada respuesta de la API incluye un encabezado único request-id. Este encabezado contiene un valor como req_018EeWyXxfu5pfWkrYcMdjWG. Al contactar al 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 oficiales proporcionan el ID de solicitud de Anthropic como una propiedad en los objetos de respuesta de nivel superior, que contiene el valor del encabezado request-id. En Claude Platform en AWS, usa el accesor de respuesta sin procesar para leer también el ID de solicitud de AWS desde los encabezados HTTP:

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

Para ejemplos de request-ID de Claude Platform en AWS en otros lenguajes, consulta IDs de solicitud.



Solicitudes largas

Evita establecer un valor grande de max_tokens sin usar la Messages API con streaming o la Message Batches API:

• Algunas redes pueden cerrar conexiones inactivas después de un período de tiempo variable, lo que puede causar que la solicitud falle o se agote el tiempo de espera sin recibir una respuesta de Anthropic.
• Las redes difieren en confiabilidad; la Message Batches API puede ayudarte a gestionar el riesgo de problemas de red al permitirte consultar los resultados en lugar de requerir una conexión de red ininterrumpida.

Si estás construyendo una integración directa con la API, debes tener en cuenta que 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 tus solicitudes a la Messages API sin streaming no se espere que excedan un tiempo de espera de 10 minutos y también establecerán una opción de socket para TCP keep-alive.

Si no necesitas procesar eventos de forma incremental, usa .stream() con .get_final_message() (Python) o .finalMessage() (TypeScript) para obtener el objeto Message completo sin escribir código de manejo de eventos:

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-4-8",
) as stream:
    message = stream.get_final_message()
print(message.content)

Consulta Streaming de mensajes para más detalles.



Errores de validación comunes



Prefill no compatible

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6 no admiten el prellenado (prefill) 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": "Prefilling assistant messages is not supported for this model."
  }
}

Usa salidas estructuradas en los modelos que lo admitan, instrucciones en la indicación del sistema, o output_config.format en su lugar.



Los bloques de pensamiento no se pueden modificar

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 devolverse exactamente como se recibió, incluidos los bloques cuyo campo thinking esté vacío. Devuelve los bloques de pensamiento sin cambios y, si tu aplicación filtra bloques de contenido por tipo antes de reenviarlos, incluye tanto thinking como redacted_thinking. Consulta Preservar bloques de pensamiento y Salida de pensamiento en Claude Fable 5 y Claude Mythos 5.



Federación de identidad web saliente deshabilitada (Claude Platform en AWS)

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.