--- title: Errores de la Claude API url: https://platform.claude.com/docs/es/api/errors description: Comprende los códigos de estado HTTP, la estructura de las respuestas de error y los ID de solicitud que devuelve la Claude API, y maneja los errores con las excepciones tipadas del SDK. --- ## 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 aparecen en esta sección. La API también devuelve un 400 cuando el uso alcanza un [límite de gasto que hayas establecido](https://platform.claude.com/docs/es/api/rate-limits#setting-your-own-spend-limit) para una organización o un espacio de trabajo, excepto los límites del [espacio de trabajo de Claude Code](https://platform.claude.com/docs/es/manage-claude/workspaces#claude-code-workspace), que pueden devolver un 429 en su lugar. * 401 - `authentication_error`: Hay un problema con tu ["API key" (clave de API)](https://platform.claude.com/docs/es/get-api-key) (por ejemplo, tiene un formato incorrecto, fue revocada o expiró; consulta [Expiración de claves](https://platform.claude.com/docs/es/manage-claude/authentication#key-expiration)). 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](https://platform.claude.com), 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](https://platform.claude.com). * 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](https://platform.claude.com/docs/es/api/errors#request-size-limits) para ver los máximos por endpoint. * 429 - `rate_limit_error`: Tu organización alcanzó un "[rate limit](https://platform.claude.com/docs/es/api/rate-limits)" (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](https://platform.claude.com/docs/es/api/rate-limits#reaching-your-spend-cap) para saber cómo reconocerlo. * 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](https://platform.claude.com/docs/es/api/errors#request-id). * 504 - `timeout_error`: Se agotó el tiempo de espera de la solicitud mientras se procesaba. Considera usar la [API de Messages con streaming](https://platform.claude.com/docs/es/build-with-claude/streaming) para solicitudes de larga duración. Consulta [Solicitudes largas](https://platform.claude.com/docs/es/api/errors#long-requests) para ver más opciones. * 529 - `overloaded_error`: La API está sobrecargada temporalmente. Los errores 529 pueden ocurrir cuando la API experimenta mucho tráfico entre todos los usuarios. En casos poco frecuentes, 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, aumenta tu tráfico de forma gradual y mantén patrones de uso constantes. 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` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`) para configurar o desactivar este comportamiento. Al recibir una respuesta con [streaming](https://platform.claude.com/docs/es/build-with-claude/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](https://platform.claude.com/docs/es/build-with-claude/streaming#error-events) para ver la estructura 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: | Tipo de endpoint | Tamaño máximo de la solicitud | | -------------------------------------------------------------------------------------- | ----------------------------- | | API de Messages | 32 MB | | API de Token Counting | 32 MB | | [API de Batch](https://platform.claude.com/docs/es/build-with-claude/batch-processing) | 256 MB | | [API de Files](https://platform.claude.com/docs/es/build-with-claude/files) | 500 MB | 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: ```json JSON { "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](https://platform.claude.com/docs/es/api/versioning), 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 El SDK oficial lanza excepciones tipadas para estos errores en lugar de devolver JSON sin procesar. Por ejemplo, un 404 aparece como `anthropic.NotFoundError` (typescript: `Anthropic.NotFoundError`; ruby: `Anthropic::Errors::NotFoundError`; java: `com.anthropic.errors.NotFoundException`; csharp: `AnthropicNotFoundException`; php: `Anthropic\Core\Exceptions\NotFoundException`; go: `*anthropic.Error`). 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](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/ruby#handling-errors) ## 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](https://platform.claude.com/docs/es/api/errors#error-shapes). 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](https://platform.claude.com/docs/es/build-with-claude/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](https://platform.claude.com/docs/es/cli-sdks-libraries/middleware). En todos los SDK excepto Ruby, usa `with_raw_response` (typescript: `.withResponse()`; java: `.withRawResponse()`; csharp: `WithRawResponse`; go: `option.WithResponseInto`; php: `->raw`) para leer cualquier otro [encabezado de respuesta](https://platform.claude.com/docs/es/api/overview#response-headers), como `anthropic-organization-id` y [`anthropic-workspace-id`](https://platform.claude.com/docs/es/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). 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`): ```bash cURL # Imprime los encabezados de la respuesta (incluido request-id); descarta el cuerpo curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # El encabezado request-id se imprime en stderr con --debug: ant --debug messages create \ --model claude-sonnet-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const message = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }); console.log("Request ID:", message._request_id); ``` ```csharp C# AnthropicClient client = new(); using var response = await client.WithRawResponse.Messages.Create(new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }] }); Console.WriteLine($"Request ID: {response.RequestID}"); ``` ```go Go client := anthropic.NewClient() var response *http.Response _, err := client.Messages.New( context.Background(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithResponseInto(&response), ) if err != nil { panic(err) } fmt.Println("Request ID:", response.Header.Get("request-id")) ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.http.HttpResponseFor; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); HttpResponseFor response = client.messages().withRawResponse().create( MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .build() ); IO.println("Request ID: " + response.requestId().orElse(null)); } ``` ```php PHP $client = new Client(); $response = $client->messages->raw->create([ 'model' => 'claude-sonnet-5', 'maxTokens' => 1024, 'messages' => [['role' => 'user', 'content' => 'Hello, Claude']], ]); echo 'Request ID: ' . $response->getHeaderLine('request-id') . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new # Lee los encabezados de respuesta en el middleware por solicitud, que recibe la # respuesta HTTP sin procesar antes de que el SDK la analice request_id = nil read_request_id = lambda do |request, call_next| response = call_next.call(request) # Las claves en response.headers están en minúsculas request_id = response.headers["request-id"] response end client.messages.create( model: Anthropic::Model::CLAUDE_SONNET_5, max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }], request_options: { middleware: [read_request_id] } ) puts "Request ID: #{request_id}" ``` ```python Python (Claude Platform on AWS) from anthropic import AnthropicAWS client = AnthropicAWS(aws_region="us-west-2") response = client.messages.with_raw_response.create( model="claude-opus-5-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello, Claude"}], ) print(f"AWS request ID: {response.headers.get('x-amzn-requestid')}") message = response.parse() print(f"Anthropic request ID: {message._request_id}") ``` ```typescript TypeScript (Claude Platform on AWS) import AnthropicAws from "@anthropic-ai/aws-sdk"; const client = new AnthropicAws({ awsRegion: "us-west-2" }); const { response: raw, request_id } = await client.messages .create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }) .withResponse(); console.log("AWS request ID:", raw.headers.get("x-amzn-requestid")); console.log("Anthropic request ID:", request_id); ``` Para ver ejemplos de ID de solicitud de Claude Platform on AWS en otros lenguajes, consulta [ID de solicitud](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws#request-ids). ## Solicitudes largas Considera usar la [API de Messages con streaming](https://platform.claude.com/docs/es/build-with-claude/streaming) o la [API de Message Batches](https://platform.claude.com/docs/es/api/messages/batches/create) para solicitudes de larga duración, especialmente las que superan los 10 minutos. Evita establecer un valor grande de `max_tokens` sin usar la [API de Messages con streaming](https://platform.claude.com/docs/es/build-with-claude/streaming) o la [API de Message Batches](https://platform.claude.com/docs/es/api/messages/batches/create): * 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 Batches](https://platform.claude.com/docs/es/api/messages/batches/create) 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](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html) puede reducir el impacto de los tiempos de espera por conexiones inactivas en algunas redes. Los [SDK](https://platform.claude.com/docs/es/cli-sdks-libraries/overview) 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 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: Una solicitud con curl imprime los eventos del stream sin procesar y no puede combinarlos en el mensaje final. Para obtener el objeto `Message` completo a partir de un stream, usa el [SDK de Claude](https://platform.claude.com/docs/es/cli-sdks-libraries/overview). ```bash CLI # La CLI hace streaming de eventos; --format jsonl emite un evento por línea ant messages create --stream --format jsonl <<'YAML' model: claude-sonnet-5 max_tokens: 128000 messages: - role: user content: Write a detailed analysis... YAML ``` ```python Python 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")) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }], model: "claude-sonnet-5" }); const message = await stream.finalMessage(); const textBlock = message.content.find((block) => block.type === "text"); if (textBlock && textBlock.type === "text") { console.log(textBlock.text); } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 128000, Messages = [new() { Role = Role.User, Content = "Write a detailed analysis..." }] }; var message = await client.Messages.CreateStreaming(parameters).Aggregate(); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 128000, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Write a detailed analysis...")), }, }) message := anthropic.Message{} for stream.Next() { event := stream.Current() if err := message.Accumulate(event); err != nil { log.Fatal(err) } } if err := stream.Err(); err != nil { log.Fatal(err) } for _, block := range message.Content { if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { fmt.Println(textBlock.Text) break } } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.helpers.MessageAccumulator; import com.anthropic.models.messages.ContentBlock; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(128000L) .addUserMessage("Write a detailed analysis...") .build(); MessageAccumulator accumulator = MessageAccumulator.create(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(accumulator::accumulate); } Message message = accumulator.message(); message.content().stream() .filter(ContentBlock::isText) .findFirst() .flatMap(ContentBlock::text) .ifPresent(textBlock -> IO.println(textBlock.text())); } ``` ```php PHP use Anthropic\Lib\Streaming\MessageAccumulator; $client = new Client(); $stream = $client->messages->createStream( model: 'claude-sonnet-5', maxTokens: 128000, messages: [['role' => 'user', 'content' => 'Write a detailed analysis...']], ); $accumulator = MessageAccumulator::forMessages(); foreach ($stream as $event) { $accumulator->accumulate($event); } echo array_find($accumulator->message()->content, static fn ($block): bool => $block->type === 'text')->text; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.stream( model: "claude-sonnet-5", max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }] ).accumulated_message puts message.content.find { it.type == :text }.text ``` Consulta [Streaming de mensajes](https://platform.claude.com/docs/es/build-with-claude/streaming#get-the-final-message-without-handling-events) para obtener más detalles. ## Errores de validación comunes ### Prefill no admitido Los modelos Claude 4.6 y posteriores y [Claude Mythos Preview](https://anthropic.com/glasswing) 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`: ```json { "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](https://platform.claude.com/docs/es/build-with-claude/structured-outputs) en los modelos que las admiten, instrucciones en la "system prompt" (indicación del sistema) o [`output_config.format`](https://platform.claude.com/docs/es/build-with-claude/structured-outputs#usage). ### 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: ```text wrap `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](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified), [Conservar los bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#preserving-thinking-blocks) y [Pensamiento conservado](https://platform.claude.com/docs/es/build-with-claude/thinking#preserved-thinking). ### 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`: ```text wrap "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](https://platform.claude.com/docs/es/build-with-claude/thinking). [Migrar al pensamiento adaptativo](https://platform.claude.com/docs/es/build-with-claude/extended-thinking#migrating-to-adaptive-thinking) muestra la correspondencia de parámetros, y [Solución de problemas del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled) 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`: ```text wrap adaptive thinking is not supported on this model ``` Usa `thinking: {"type": "enabled", "budget_tokens": N}` en estos modelos; consulta [Pensamiento extendido](https://platform.claude.com/docs/es/build-with-claude/extended-thinking) para ver la configuración y [Solución de problemas del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive) para la solución a partir del síntoma. ### El pensamiento no se puede desactivar En Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/es/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/es/models/mythos-5/overview), Claude Opus 5.5 y [Claude Mythos Preview](https://anthropic.com/glasswing), 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: ```text wrap "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: ```text wrap "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: ```text wrap 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](https://platform.claude.com/docs/es/build-with-claude/effort) `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: ```text wrap 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: ```text wrap 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 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`: ```text wrap "thinking.type.between_tools" is not supported for this model. ``` Para ver las soluciones, consulta [Solución de problemas del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools), 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](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled). ### Uso forzado de herramientas no admitido Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y [Claude Mythos 5.1](https://platform.claude.com/docs/es/models/mythos-5-1/overview) 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](https://platform.claude.com/docs/es/build-with-claude/token-counting), devuelve un 400 `invalid_request_error`: ```text wrap 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use) para mantener las entradas de las herramientas válidas según el esquema, o [salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs) cuando necesites que la propia respuesta tenga una estructura JSON fija. Consulta [Forzar el uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools#forcing-tool-use). ### Versión de la herramienta de uso de computadora no admitida En la API de Claude y Google Cloud, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5 admiten el [uso de computadora](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool) solo como el conjunto de herramientas `computer_toolset_20260801`. En esas plataformas, enviar a cualquiera de estos modelos una entrada de `tools` del tipo anterior `computer_20251124` o `computer_20250124`, 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í: ```text wrap '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`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Para migrar desde `computer_20250124`, consulta [Migra el uso de computadora al conjunto de herramientas](https://platform.claude.com/docs/es/models/haiku-5-5/migration-guide#computer-use-toolset) en la guía de migración de Claude Haiku 5.5. Los modelos anteriores que admiten el conjunto de herramientas siguen aceptando `computer_20251124`, al igual que Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 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, Claude Sonnet 5.5 y Claude Haiku 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: ```text wrap 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 y Claude Haiku 5.5, `block_binding` solo funciona con `thinking: {"type": "adaptive"}`. Con `between_tools` en Claude Sonnet 5.5, o `thinking: {"type": "disabled"}` en Claude Haiku 5.5, mantén el historial en modo de solo anexar, o elimina los bloques de pensamiento a partir del turno editado. 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](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#prefix-check) y [Solución de problemas del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-block-signature). Enviar `thinking.block_binding` sin el [encabezado beta](https://platform.claude.com/docs/es/api/beta-headers) `thinking-binding-controls-2026-08-01` devuelve un 400 `invalid_request_error` cuyo mensaje termina en: ```text wrap 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](https://platform.claude.com/docs/es/build-with-claude/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](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) para obtener más detalles. ## Próximos pasos Soluciones a partir del síntoma para errores 400 de configuración del pensamiento, bloques de pensamiento vacíos y detenciones por `max_tokens`. 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, incluidos los deltas de texto, de uso de herramientas y de pensamiento extendido.