Errores de la Claude API

Errores HTTP

La API sigue un formato predecible de códigos de error HTTP:

• 400 - invalid_request_error: Hay un problema con el formato o el contenido de tu solicitud. La API también podría usar este tipo de error para otros códigos de estado 4XX que no aparecen en esta sección. La API también devuelve un 400 cuando el uso alcanza un límite de gasto que hayas establecido para una organización o un espacio de trabajo. Los límites del espacio de trabajo de Claude Code son la excepción: pueden devolver un 429 en su lugar. Si el mensaje nombra un problema con tu solicitud, búscalo en Errores de validación comunes.

• 401 - authentication_error: Hay un problema con tu “API key” (clave de API) (por ejemplo, tiene un formato incorrecto, fue revocada o expiró; consulta Expiración de claves). En Claude Platform on AWS, esto también puede indicar un problema con tus credenciales de AWS o con tu firma SigV4.

  Un 401 cuyo mensaje comienza con CORS requests are not allowed for this Organization no es un problema con tu clave de API. La solicitud incluyó un encabezado Origin, que los navegadores agregan, y tu organización no puede llamar a la API de Claude directamente desde un navegador. El mensaje continúa con because of custom retention settings o because of its settings. El primero aparece solo para acuerdos de retención de datos como “zero data retention” (retención de datos cero), o ZDR; el segundo es el caso general, que incluye la Compliance API. Ningún cambio en la solicitud del navegador lo soluciona, así que envía la solicitud desde tu propio back end; consulta Aplicaciones basadas en navegador.

• 402 - billing_error: Hay un problema con tu información de facturación o de pago. Revisa tus datos de pago en la Claude Console, o en AWS Marketplace si usas Claude Platform on AWS.

• 403 - permission_error: Tu clave de API no tiene permiso para usar el recurso especificado. Revisa el acceso de tu organización y la configuración del espacio de trabajo en la Claude Console.

• 404 - not_found_error: No se encontró el recurso solicitado. Revisa 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 se modificó de forma concurrente, o un valor que debe ser único ya está en uso. Resuelve el conflicto y luego vuelve a intentar la solicitud.

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

• 429 - rate_limit_error: Tu organización alcanzó un “rate limit” (límite de velocidad), llegó al tope de gasto mensual de su nivel de uso o alcanzó un límite de gasto en el espacio de trabajo de Claude Code. Un 429 por tope de gasto del nivel no incluye el encabezado retry-after y sigue fallando hasta que se restablece el acceso; consulta Alcanzar tu tope de gasto para saber cómo reconocerlo. Un aumento brusco en el uso también puede provocar un 429 incluso cuando estás por debajo de tus límites de velocidad; consulta “Ramp limits” (límites de rampa).

• 500 - api_error: Ocurrió un error inesperado interno en los sistemas de Anthropic. Vuelve a intentar la solicitud con “exponential backoff” (retroceso exponencial); si el error persiste, contacta a soporte con el ID de solicitud. Si en cambio el tipo de error es timeout_error, consulta la entrada del 504.

• 504 - timeout_error: Se agotó el tiempo de espera de la solicitud mientras se procesaba. La API también devuelve timeout_error con otros códigos de estado, como un 500 cuando una solicitud alcanza el límite de tiempo del servidor antes de que comience la respuesta. Para solicitudes de larga duración a la API de Messages, usa la API de Messages con streaming. Consulta Solicitudes largas para ver más opciones.

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

El SDK oficial reintenta 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. El cliente del SDK acepta max_retries para configurar o desactivar este comportamiento.

Al recibir una respuesta con streaming mediante “server-sent events” (eventos enviados por el servidor), o 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 ver la estructura de los errores a mitad del stream.

Límites de tamaño de las solicitudes

La API de Claude de primera parte aplica estos límites de tamaño de solicitud. Para otras plataformas, consulta la descripción general de la API.

Si superas estos límites, recibirás un error 413 request_too_large. En la API de Claude de primera parte, Cloudflare devuelve este error antes de que la solicitud llegue a los servidores de la API.

Formas de los errores

La API siempre devuelve los errores como JSON, con un objeto error de nivel superior que siempre incluye un valor type y un valor 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 de la API, los valores dentro de estos objetos pueden ampliarse, y pueden aparecer nuevos valores de type.

Tipos de error del SDK

El SDK oficial lanza excepciones tipadas para estos errores en lugar de devolver JSON sin procesar. Por ejemplo, un 404 aparece como anthropic.NotFoundError. El SDK de Go tiene un único tipo de error para todos los estados, *anthropic.Error: ramifica según StatusCode. Captura las clases tipadas del SDK en lugar de comparar cadenas de los mensajes de error, manejando primero las clases más específicas. La página de tu SDK documenta la 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 las respuestas de error. Cuando contactes al soporte por una solicitud específica, incluye este ID para ayudar a resolver tu problema rápidamente.

En Claude Platform on AWS, las respuestas incluyen dos ID de solicitud: el ID de solicitud de AWS (x-amzn-requestid, principal, indexado en CloudTrail) y el ID de solicitud de Anthropic (request-id, secundario). Usa el ID de solicitud de AWS para las búsquedas en CloudTrail y el ID de solicitud de Anthropic para los tickets de soporte de Anthropic.

Los SDK de Python y TypeScript exponen el ID de solicitud como una propiedad _request_id en los objetos de respuesta de nivel superior. Los SDK de C#, Go, Java y PHP lo exponen mediante sus accesores de respuesta sin procesar, y el SDK de Ruby mediante middleware. En todos los SDK excepto Ruby, usa with_raw_response para leer cualquier otro encabezado de respuesta, como anthropic-organization-id y anthropic-workspace-id. En Ruby, usa el mismo middleware. En Claude Platform on AWS, usa también el accesor de respuesta sin procesar para leer 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 ver ejemplos de ID de solicitud de Claude Platform on AWS en otros lenguajes, consulta ID de solicitud.

Solicitudes largas

Evita establecer un valor grande de max_tokens sin usar la API de Messages con streaming o la API de Message BatchesVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.:

• Algunas redes pueden cerrar las 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 API de Message BatchesVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. puede ayudarte a gestionar el riesgo de problemas de red al permitirte consultar periódicamente los resultados en lugar de requerir una conexión de red ininterrumpida.

Si estás creando una integración directa con la API, configurar un keep-alive de socket TCP puede reducir el impacto de los tiempos de espera por conexiones inactivas en algunas redes.

El Anthropic SDK valida que no se espere que tus solicitudes a la API de Messages sin streaming excedan un tiempo de espera de 10 minutos. También establece una opción de socket para TCP keep-alive.

Si no necesitas procesar los eventos de forma incremental, el SDK puede 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 Obtener el mensaje final sin manejar eventos para obtener más detalles.

Errores de validación comunes

Prefill no admitido

Los modelos Claude 4.6 y posteriores y Claude Mythos Preview no admiten el “prefill” (prellenado) de mensajes del asistente. Enviar una solicitud con un último mensaje del asistente prellenado a cualquiera de estos modelos devuelve un 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."
  }
}

En su lugar, usa salidas estructuradas en los modelos que las admiten, instrucciones en la “system prompt” (indicación del sistema) o output_config.format.

Los bloques de pensamiento no se pueden modificar

Si los bloques de pensamiento de la solicitud no coinciden con lo que devolvió la API, la solicitud puede recibir un 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 “tool use” (uso de herramientas), devuelve cada bloque thinking y redacted_thinking del turno del asistente exactamente como se recibió, incluidos los bloques cuyo campo thinking está vacío. Si tu aplicación filtra los bloques de contenido por tipo antes de reenviarlos, incluye tanto thinking como redacted_thinking. Este es un fallo distinto de la verificación de prefijo, cuyo error indica que un bloque está vinculado a una conversación diferente. Establecer prefix_mismatch_behavior podría no resolverlo. Consulta la solución para bloques de pensamiento modificados en Solución de problemas del pensamiento.

Pensamiento extendido no admitido

Los modelos Claude 4.7 y posteriores no admiten el “extended thinking” (pensamiento extendido). Enviar thinking: {"type": "enabled"} a cualquiera de estos modelos devuelve un 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.

En su lugar, usa el pensamiento adaptativo. Para ver la correspondencia de parámetros, consulta Migrar al pensamiento adaptativo. Para solucionar el error a partir de su síntoma, consulta Un error 400 indica que "thinking.type.enabled" no es compatible.

Pensamiento adaptativo no admitido

Los modelos que solo admiten el pensamiento extendido (los modelos Claude 4.5 y anteriores) rechazan thinking: {"type": "adaptive"} con un 400 invalid_request_error:

adaptive thinking is not supported on this model

Usa thinking: {"type": "enabled", "budget_tokens": N} en estos modelos; consulta Pensamiento extendido para ver la configuración y la solución, partiendo del síntoma, para el error de pensamiento adaptativo en Solución de problemas del pensamiento.

El pensamiento no se puede desactivar

En Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 y Claude Mythos Preview, el pensamiento siempre está activado. Enviar thinking: {"type": "disabled"} a cualquiera de estos modelos devuelve un 400 invalid_request_error. En todos estos modelos excepto Claude Mythos Preview, el mensaje dice:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

En Claude Mythos Preview, el único de estos modelos que acepta el pensamiento extendido, el mensaje dice:

"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 Sonnet 5.5, el pensamiento no se puede establecer en disabled. Usa thinking: {"type": "between_tools"} para la configuración de pensamiento más baja, que desactiva el pensamiento inicial. Enviar thinking: {"type": "disabled"} devuelve un 400 invalid_request_error con este mensaje:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

Con un esfuerzo xhigh o max, una solicitud con between_tools también devuelve un 400 invalid_request_error. El mensaje de error indica que el pensamiento está desactivado porque between_tools no tiene pensamiento inicial:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

Con between_tools, el esfuerzo no puede cambiar a mitad de la conversación: un output_config.effort por mensaje que difiera del nivel vigente devuelve un error 400. El error indica la posición del mensaje que estableció el nuevo nivel:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

Claude Haiku 5.5 acepta thinking: {"type": "disabled"} y lo somete a los mismos dos límites de esfuerzo que se aplican a between_tools: con un esfuerzo xhigh o max, o con un output_config.effort por mensaje que difiera del nivel vigente, la solicitud devuelve un 400 invalid_request_error con el mensaje correspondiente mostrado anteriormente.

En ambos mensajes, “enable thinking” se refiere al pensamiento adaptativo: omite el campo thinking o envía thinking: {"type": "adaptive"}. Claude Sonnet 5.5 y Claude Haiku 5.5 también rechazan "enabled" con un error 400. Para variar el esfuerzo en cada turno, usa el pensamiento adaptativo.

Enviar thinking: {"type": "between_tools"} a cualquier modelo que no sea Claude Sonnet 5.5 devuelve un 400 invalid_request_error:

"thinking.type.between_tools" is not supported for this model.

Para ver las soluciones, consulta los errores de between_tools y de esfuerzo en Solución de problemas del pensamiento.

Omite el parámetro thinking y la solicitud se ejecutará con pensamiento adaptativo. Para mantener el contenido del pensamiento fuera de las respuestas sin desactivar el pensamiento, establece display: "omitted" en la configuración de pensamiento. Consulta la solución para el error de pensamiento desactivado en Solución de problemas del pensamiento.

Uso forzado de herramientas no admitido

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1 no admiten el uso forzado de herramientas. Enviar tool_choice: {"type": "any"} o tool_choice: {"type": "tool", "name": "..."} a cualquiera de estos modelos, incluso en el endpoint de conteo de tokens, devuelve un 400 invalid_request_error:

tool_choice: type "tool" and "any" are not supported for this model.

Se aceptan tool_choice: {"type": "auto"} (el valor predeterminado) y {"type": "none"}. Usa auto con el uso estricto de herramientas para mantener las entradas de las herramientas válidas según el esquema, o salidas estructuradas cuando necesites que la propia respuesta tenga una estructura JSON fija. Consulta Forzar el uso de herramientas.

Versión de la herramienta de uso de computadora no admitida

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5 devuelven un error 400 para cualquier versión de la herramienta de uso de computadora que no acepten. En la API de Claude, eso incluye computer_20251124 con su encabezado beta. No aceptan computer_20250124 en ninguna plataforma. El mensaje invalid_request_error de la API de Claude indica el tipo rechazado y, después de Did you mean one of, enumera los tipos de herramienta que acepta el modelo. Para Claude Opus 5.5, el mensaje comienza así:

'claude-opus-5-5' does not support tool types: computer_20251124.

La API de Claude devuelve el mismo mensaje para cualquier tipo de herramienta definida por Anthropic que el modelo solicitado no admita. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5 admiten el uso de computadora mediante el conjunto de herramientas computer_toolset_20260801. Declara {"type": "computer_toolset_20260801"} sin el encabezado beta y actualiza el bucle de tu agente como se describe en Migrar desde computer_20251124. Para migrar desde computer_20250124, consulta Mover el uso de computadora al conjunto de herramientas en la guía de migración de Claude Haiku 5.5.

En Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5 también aceptan la herramienta computer_20251124 con el encabezado beta computer-use-2025-11-24. Con la API de InvokeModel de Amazon Bedrock, envía computer-use-2025-11-24 en el arreglo anthropic_beta del cuerpo de la solicitud en lugar de en un encabezado. Para esa API, consulta Claude en Amazon Bedrock (bedrock-runtime). Para ver los modelos que se deben usar con cada versión anterior, consulta Versiones anteriores de la herramienta.

Bloque de pensamiento vinculado a una conversación diferente

Este error 400 invalid_request_error significa que un bloque de pensamiento que enviaste de vuelta no superó la verificación de prefijo. Compara system, tools y los mensajes anteriores al bloque con lo que enviaste cuando el modelo lo produjo. Para saber qué cambios importan, consulta Qué cuenta como un cambio. El mensaje de error comienza con la posición del primer bloque que no supera la verificación de prefijo:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

Reenviar el mismo historial falla de la misma manera. Corregir el código que hizo la edición no ayuda a esta conversación si la edición sigue en su historial. Para continuar, haz una de las siguientes acciones:

• Envía el encabezado beta thinking-binding-controls-2026-08-01 y establece thinking.block_binding.prefix_mismatch_behavior en "drop_block", en el reintento y en cada solicitud posterior de esa conversación. En Claude Sonnet 5.5 y Claude Haiku 5.5, block_binding solo funciona con thinking: {"type": "adaptive"}.
• Elimina el bloque que nombra el error y cada bloque thinking y redacted_thinking posterior a él, en ese mensaje y en cada mensaje posterior. Reintenta y deja los bloques eliminados fuera de las solicitudes posteriores.

Para evitar que las conversaciones nuevas fallen, mantén el historial en modo “append-only” (solo de adición). Consulta la solución para una firma de bloque de pensamiento no válida en Solución de problemas del pensamiento.

Enviar thinking.block_binding sin el encabezado beta thinking-binding-controls-2026-08-01 devuelve un 400 invalid_request_error cuyo mensaje termina en:

block_binding: Extra inputs are not permitted

Agrega el encabezado, activa el pensamiento o elimina el campo.

Federación de identidad web saliente desactivada (Claude Platform on AWS)

Si cada solicitud a Claude Platform on AWS devuelve "Outbound web identity federation is disabled for your account", ejecuta aws iam enable-outbound-web-identity-federation una vez por cada cuenta de AWS. Consulta Habilitar la federación de identidad web saliente para obtener más detalles.

Próximos pasos