Errores de la Claude API

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 que no se enumeran 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, excepto en el caso de los límites del espacio de trabajo de Claude Code, que pueden devolver un 429 en su lugar.

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

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

• 500 - api_error: Se produjo un error inesperado interno en los sistemas de Anthropic. Vuelve a intentar la solicitud con retroceso exponencial; si el error persiste, contacta al soporte con el ID de solicitud.

• 504 - timeout_error: Se agotó el tiempo de espera de la solicitud mientras se procesaba. Considera usar la API de Messages con streaming para solicitudes de larga duración. Consulta Solicitudes largas para ver más opciones.

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

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

Al recibir una respuesta en streaming mediante "server-sent events" (eventos enviados por el servidor), o SSE, puede producirse 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 forma de los errores a mitad del stream.

Límites de tamaño de las solicitudes

La API aplica límites de tamaño a las solicitudes:

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

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, los valores dentro de estos objetos pueden ampliarse, y es posible que los valores de type aumenten con el tiempo.

Tipos de error de los SDK

Los SDK 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 varían según el lenguaje. 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, y maneja primero las clases más específicas. La página de cada 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 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 Batches:

• 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 varían en fiabilidad. La API de Message Batches 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 TCP socket keep-alive puede reducir el impacto de los tiempos de espera por conexiones inactivas en algunas redes.

Los SDK validan que no se espere que tus solicitudes a la API de Messages sin streaming superen un tiempo de espera de 10 minutos. También establecen una opción de socket para TCP keep-alive.

Si no necesitas procesar los eventos de forma incremental, los SDK 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 Mensajes en streaming 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 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 el mensaje más reciente del asistente contiene bloques thinking o redacted_thinking que se editaron, reordenaron, filtraron o reconstruyeron antes de enviarlos de vuelta a la API, la solicitud devuelve 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), 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 los bloques de contenido por tipo antes de reenviarlos, incluye tanto thinking como redacted_thinking. Consulta Solución de problemas del pensamiento, Conservar los bloques de pensamiento y Pensamiento conservado.

Pensamiento extendido no admitido

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 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. Migrar al pensamiento adaptativo muestra la correspondencia de parámetros, y Solución de problemas del pensamiento cubre la solución a partir del síntoma.

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 Solución de problemas del pensamiento para la solución a partir del síntoma.

El pensamiento no se puede desactivar

En 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:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Con un esfuerzo xhigh o max, una solicitud con between_tools también devuelve un 400 invalid_request_error. El mensaje 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.

En ambos mensajes, "enable thinking" se refiere al pensamiento adaptativo: omite el campo thinking o envía thinking: {"type": "adaptive"}. Claude Sonnet 5.5 rechaza "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 Solución de problemas del pensamiento, que cubre los errores de between_tools y de esfuerzo.

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 del pensamiento. Consulta Solución de problemas del pensamiento.

Uso forzado de herramientas no admitido

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 forma JSON fija. Consulta Forzar el uso de herramientas.

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

En la API de Claude y en Google Cloud, Claude Opus 5.5 y Claude Sonnet 5.5 admiten el uso de computadora solo como el toolset computer_toolset_20260801. En esas plataformas, enviar a cualquiera de los dos modelos una entrada de tools del tipo anterior computer_20251124 (con el encabezado beta de esa herramienta) devuelve un 400 invalid_request_error. El mensaje indica el tipo rechazado y luego enumera los tipos de herramienta que el modelo sí acepta después de Did you mean one of. Para Claude Opus 5.5, comienza así:

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

La API devuelve el mismo mensaje para cualquier tipo de herramienta definido por Anthropic que el modelo solicitado no admita. Declara {"type": "computer_toolset_20260801"} sin el encabezado beta y actualiza el bucle de tu agente como se describe en Migrar desde computer_20251124. Los modelos anteriores que admiten el toolset siguen aceptando computer_20251124, al igual que Claude Opus 5.5 y Claude Sonnet 5.5 en Amazon Bedrock.

El bloque de pensamiento ya no coincide con la conversación

En Claude Fable 5.1, Claude Opus 5.5 y Claude Sonnet 5.5, la API acepta un bloque de pensamiento reenviado solo mientras la indicación system, las tools y los mensajes que lo precedieron no hayan cambiado. Para las cuentas nuevas creadas a partir del 31 de agosto de 2026, y para cualquier solicitud que establezca thinking.block_binding.prefix_mismatch_behavior en "error", un bloque reenviado cuyo historial anterior haya cambiado se rechaza con un 400 invalid_request_error (con "drop_block", la API descarta el bloque y la solicitud se completa correctamente). El mensaje comienza con la posición del primer bloque que falla:

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

Sin el encabezado beta thinking-binding-controls-2026-08-01, el mensaje también menciona ese encabezado. Mantén el historial de la conversación en modo de solo anexar, o envía el encabezado beta con prefix_mismatch_behavior: "drop_block" para descartar el bloque y continuar. En Claude Sonnet 5.5, block_binding solo funciona con thinking: {"type": "adaptive"}. Con between_tools, mantén el historial en modo de solo anexar, o elimina los bloques de pensamiento desde el turno editado en adelante. Un bloque de un modelo que el modelo de destino no puede leer se descarta en lugar de rechazarse. Consulta Mantener el prefijo sin cambios y 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 o elimina el campo.

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

Si todas las solicitudes a Claude Platform on AWS devuelven "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