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 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.

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

• 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 límite de velocidad.

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

• 504 - timeout_error: La solicitud agotó el tiempo de espera durante el procesamiento. Considera usar 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 en 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 de forma predeterminada, 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.



Límites de tamaño de solicitud

La API aplica límites de tamaño de solicitud:

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



Formas de error

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.



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 las clases 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:

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



ID de solicitud

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 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 los 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.



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 descartar conexiones inactivas después de un período de tiempo variable, lo que puede hacer que la solicitud falle o 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, 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 de la Messages API 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(message.content[0].text)

Consulta Streaming de mensajes para más detalles.



Errores de validación comunes



Prefill no soportado

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 en su lugar salidas estructuradas en los modelos que lo admiten, instrucciones en la indicación del sistema, o output_config.format.



Los bloques de pensamiento no pueden modificarse

Si el mensaje más reciente del asistente contiene bloques thinking o redacted_thinking que fueron editados, reordenados, filtrados o reconstruidos antes de ser enviados 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 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.



Próximos pasos