|

3 soluciones para corregir el error de scope de cache_control en Claude Code Bedrock: Guía completa de resolución de problemas para fallos en la reanudación de sesiones con –resume

PorAPIYI - Stable and affordable AI API

Si te has encontrado con este error al conectar Claude Code con AWS Bedrock:

InvokeModelWithResponseStream: operation error Bedrock Runtime:
InvokeModelWithResponseStream, https response error StatusCode: 400,
RequestID: 47574f13-c884-4b12-a003-6d0cf252d8dd,
ValidationException: system.1.cache_control.***.scope:
Extra inputs are not permitted

Especialmente si aparece con frecuencia al usar --resume para retomar sesiones anteriores, es un problema de compatibilidad conocido, no un error en tu configuración.

La causa raíz es que Claude Code envía un campo scope que Bedrock no admite. Puedes solucionarlo configurando una sola variable de entorno en 30 segundos.

Valor principal: Al terminar de leer, entenderás el origen de este error, dominarás 3 soluciones y sabrás cómo configurarlo correctamente en CLI, VS Code, JetBrains y otros entornos.

claude-code-bedrock-cache-control-scope-error-fix-resume-guide-es 图示

Análisis profundo del error en Claude Code con Bedrock

Para entender este error, es necesario conocer un contexto clave: el nivel de soporte para cache_control difiere entre la API nativa de Anthropic y AWS Bedrock.

La causa técnica del error

En enero de 2026, Anthropic lanzó una función Beta en su API nativa llamada prompt-caching-scope-2026-01-05, que añadió el campo scope al objeto cache_control:

{
  "cache_control": {
    "type": "ephemeral",
    "scope": "turn"
  }
}

Desde la versión v2.1.24 de Claude Code, este campo scope se incluye por defecto en las solicitudes a la API.

El problema radica en que: AWS Bedrock no reconoce el campo scope y su validación de esquema es extremadamente estricta; si encuentra cualquier campo desconocido, devuelve directamente un error 400.

Característica API nativa de Anthropic AWS Bedrock
cache_control.type: "ephemeral" Soportado Soportado
cache_control.ttl: "5m" Soportado Soportado
cache_control.ttl: "1h" Soportado Soportado (desde enero de 2026)
cache_control.scope Soportado (Beta) No soportado, error 400
Cabeceras Beta Aceptadas Rechazadas (error de flag beta inválido)
Estrategia de validación Flexible (ignora campos desconocidos) Estricta (rechaza campos desconocidos)

En pocas palabras: la API nativa de Anthropic es más tolerante e ignora los campos que no reconoce. Bedrock es estricto y los rechaza directamente. Claude Code envía un campo que Bedrock no entiende, y este último lanza el error.

🎯 Recomendación técnica: Este problema solo afecta a los usuarios que invocan a Claude a través de AWS Bedrock. Si utilizas la API nativa de Anthropic (por ejemplo, a través de la plataforma APIYI apiyi.com), no te encontrarás con este error, ya que la API nativa soporta completamente el campo scope.

¿Por qué --resume en Claude Code es más propenso a este error?

Aunque este error no es exclusivo de --resume, es cierto que al restaurar una sesión histórica con este comando, la probabilidad de que ocurra aumenta. Las razones son las siguientes:

claude-code-bedrock-cache-control-scope-error-fix-resume-guide-es 图示

Mecanismo interno de --resume:

  1. Carga de la sesión histórica: Lee el registro completo de la conversación desde ~/.claude/projects/<proyecto>/<ID_sesión>.jsonl.
  2. Reconstrucción del contexto: Reensambla el mensaje del sistema, las definiciones de herramientas y todos los mensajes históricos en un array de mensajes completo.
  3. Optimización de caché: Dado que el contexto restaurado suele ser grande (contiene el historial completo), Claude Code establece puntos de interrupción de cache_control de forma más agresiva en los mensajes del sistema para optimizar costes.
  4. Envío de la solicitud: La primera invocación a la API ya incluye el contexto reconstruido completo + cache_control (con el campo scope).

Punto clave: Al restaurar una sesión, el contexto es mayor → la optimización de caché es más agresiva → el campo cache_control aparece con mayor frecuencia → la probabilidad de activar el error es mayor.

Iniciar una sesión nueva también puede activarlo, pero como el contexto inicial es más pequeño, las marcas de caché pueden no ser tan densas.

Solución 1 para errores de Claude Code en Bedrock: Desactivar las funciones Beta experimentales (Recomendado)

Esta es la opción más recomendada: soluciona el error y, al mismo tiempo, mantiene la funcionalidad básica de Prompt Caching.

Principio de la solución

Al configurar CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, Claude Code realizará lo siguiente:

  • Eliminará los encabezados Beta de las solicitudes (como prompt-caching-scope-2026-01-05).
  • Eliminará el campo scope dentro de cache_control.
  • Mantendrá los campos compatibles con Bedrock, como cache_control.type y cache_control.ttl.

En otras palabras, seguirás disfrutando de la optimización de costes que ofrece el Prompt Caching, simplemente sin utilizar la nueva funcionalidad de scope.

Configuración en la terminal CLI

macOS / Linux:

# Configuración temporal (válida para la sesión de terminal actual)
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Configuración permanente (añadir al archivo de configuración del shell)
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.zshrc
source ~/.zshrc

# Si usas bash
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

# Configuración temporal
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"

# Configuración permanente
[System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS", "1", "User")

Una vez configurado, ejecuta Claude Code directamente:

# Iniciar nueva sesión
claude

# Reanudar sesión (ahora sin errores)
claude --resume

Configuración de la extensión de VS Code (¡Importante!)

La extensión de VS Code no lee las variables de entorno del shell; aunque las hayas configurado en .zshrc, la extensión de Claude Code en VS Code no podrá verlas. Debes configurarlas de la siguiente manera:

Método 1: Modificar el archivo de configuración global de Claude (Recomendado)

Edita ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Método 2: A través de la configuración de VS Code

Abre la configuración de VS Code → busca claude → localiza la opción de configuración de variables de entorno → añade CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Configuración en IDEs de JetBrains

Los plugins de Claude Code para la familia de IDEs de JetBrains (IntelliJ, WebStorm, PyCharm, etc.) también requieren una configuración independiente:

Edita ~/.claude/settings.json (comparte el mismo archivo que VS Code):

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

💡 Consejo: ~/.claude/settings.json es el archivo de configuración global de Claude Code; todos los clientes (CLI, VS Code, JetBrains) lo leerán. Configurar las variables de entorno aquí es la forma más sencilla, ya que un solo cambio aplica para todas las plataformas.

Solución 2 para errores de Claude Code en Bedrock: Desactivar el Prompt Caching

Si la solución 1 no resuelve tu problema (en casos muy excepcionales), puedes desactivar el Prompt Caching por completo.

Principio de la solución

Al configurar DISABLE_PROMPT_CACHING=1, Claude Code eliminará todos los campos cache_control de las solicitudes. Sin cache_control, no habrá scope y el error desaparecerá por completo.

Consecuencia: Pierdes la optimización de costes del Prompt Caching. En escenarios de conversaciones largas, esto podría traducirse en mayores costes de tokens.

Método de configuración

# CLI
export DISABLE_PROMPT_CACHING=1

# ~/.claude/settings.json (universal para todas las plataformas)
{
  "env": {
    "DISABLE_PROMPT_CACHING": "1"
  }
}

¿Cuándo elegir la solución 2?

Escenario Elegir solución 1 Elegir solución 2
Usuario general de Bedrock ✅ Recomendado
El error persiste tras la solución 1 ✅
Uso de pasarelas como LiteLLM ✅ Más seguro
Conversaciones cortas, sin importar costes ✅ Sin impacto
Conversaciones largas, optimización de costes ✅ Mantiene caché ❌ Aumentará costes

Solución de errores de Claude Code en Bedrock: Configuración de doble seguridad

Configura ambas variables de entorno simultáneamente para garantizar que se eliminen todos los campos no compatibles con Bedrock.

# CLI
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1"
  }
}

Esta es la configuración más segura, ideal para entornos de producción donde se requiere una estabilidad absoluta.

🚀 Otra alternativa: Si no quieres complicarte con variables de entorno ni estar limitado por los problemas de compatibilidad de Bedrock, considera cambiar a la API nativa de Anthropic. A través de la plataforma APIYI (apiyi.com), puedes acceder directamente a las interfaces nativas de Anthropic, con soporte completo para todas las funciones de Prompt Caching (incluido scope) y sin necesidad de una cuenta de AWS.

Proceso completo de resolución de errores de Claude Code en Bedrock

Si no estás seguro de qué solución aplicar, sigue este flujo de trabajo:

claude-code-bedrock-cache-control-scope-error-fix-resume-guide-es 图示

Paso 1: Confirmar el tipo de error

Comprueba si el mensaje de error contiene las siguientes palabras clave:

cache_control.***.scope: Extra inputs are not permitted

O

ValidationException: ... cache_control ... scope

Si es así, significa que es un problema de compatibilidad con el campo scope.

Paso 2: Confirmar la ruta de invocación

# Comprobar el endpoint de API que utiliza Claude Code actualmente
echo $ANTHROPIC_BASE_URL
echo $CLAUDE_CODE_USE_BEDROCK

Si has configurado CLAUDE_CODE_USE_BEDROCK=1 o variables relacionadas con Bedrock como AWS_REGION, significa que estás utilizando Bedrock.

Paso 3: Aplicar la corrección

# Primero prueba la solución 1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Prueba si se ha solucionado
claude --resume

Paso 4: Verificar la corrección

# Verificar si la variable de entorno está activa
echo $CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
# Debería mostrar: 1

# Probar una nueva sesión
claude

# Probar a reanudar una sesión
claude --resume

Paso 5: Si el error persiste

# Añadir la solución 2
export DISABLE_PROMPT_CACHING=1

# Comprobar también settings.json
cat ~/.claude/settings.json

Asegúrate de que el formato de settings.json sea correcto:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1"
  }
}

🎯 Consejo técnico: Si utilizas un proxy como LiteLLM para conectar con Bedrock, LiteLLM ha incorporado desde marzo de 2026 la función de eliminar automáticamente el campo scope (PR #22867). Actualizar a la última versión de LiteLLM también puede solucionar este problema. Si buscas una solución de acceso a la API de Claude más estable, APIYI (apiyi.com) ofrece canales de API nativos de Anthropic, los cuales no están sujetos a este tipo de limitaciones de compatibilidad.

Otros problemas de compatibilidad comunes con Claude Code y Bedrock

cache_control.scope no es el único obstáculo de compatibilidad en Bedrock. A continuación, se detallan problemas similares que los usuarios de Bedrock encuentran con frecuencia:

Palabra clave del error Causa Método de reparación
cache_control.scope: Extra inputs El campo scope no es compatible CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
invalid beta flag Flag Beta no compatible CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
thinking: undefined Formato de parámetro thinking incompatible Actualizar Claude Code a la última versión
Relacionado con context_management Campo de gestión de contexto no compatible CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
eager_input_streaming Optimización de streaming de entrada no compatible CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

La mayoría de estos problemas pueden resolverse de forma definitiva con CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, ya que estos campos no compatibles son, en esencia, funciones Beta de la API nativa de Anthropic.

💰 Optimización de costes: El almacenamiento en caché de indicaciones (Prompt Caching) de Bedrock solo admite TTL de 5 minutos y 1 hora. Si tu caso de uso depende mucho del caché, acceder a la API nativa de Anthropic a través de APIYI (apiyi.com) te permite obtener estrategias de caché más flexibles, evitando al mismo tiempo los costes de depuración derivados de los problemas de compatibilidad mencionados.

Preguntas frecuentes sobre errores de Claude Code en Bedrock

Q1: ¿He configurado las variables de entorno pero sigo recibiendo errores en VS Code?

La extensión de VS Code no hereda las variables de entorno que configuras en .zshrc o .bashrc. Debes configurarlas a través del campo env en el archivo ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Después de configurarlo, reinicia VS Code (no solo recargues la ventana, ciérralo por completo y ábrelo de nuevo) para asegurarte de que la configuración surta efecto.

Q2: ¿Desactivar el Prompt Caching afecta al rendimiento?

No afecta a la calidad de la salida del modelo ni a la velocidad de respuesta. El Prompt Caching es solo un mecanismo de optimización de costes; cuando hay un acierto de caché, se reducen los costes de procesamiento repetido de tokens. Al desactivarlo, cada solicitud se factura en su totalidad, pero el rendimiento del modelo es exactamente el mismo. Para conversaciones cortas, la diferencia de coste es mínima. En escenarios de conversaciones largas, el caché puede ahorrar entre un 30% y un 50% en los costes de tokens de entrada.

Q3: ¿Se solucionará este problema oficialmente?

Es un problema conocido y hay varios tickets en GitHub que lo rastrean (#23220, #41731, etc.). Sin embargo, dado que la estrategia de validación de esquema de Bedrock es un comportamiento del lado de AWS, es difícil para Anthropic resolverlo completamente desde el lado de Claude Code. La solución actual de variables de entorno es la recomendada oficialmente. A largo plazo, es posible que AWS Bedrock deba flexibilizar la validación de esquemas o admitir el campo scope.

Q4: ¿Tengo este problema si uso Google Vertex AI?

Sí. Google Vertex AI tampoco admite el campo cache_control.scope y mostrará errores similares. La solución es la misma: configurar CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1. Los usuarios de Vertex AI también deben prestar atención a la configuración relacionada con CLAUDE_CODE_USE_VERTEX=1.

Q5: ¿Cuál es la diferencia entre –resume y -c (–continue)? ¿Las condiciones para activar el error son las mismas?
  • --resume / -r: Abre el selector de sesiones para elegir cualquier sesión histórica y reanudarla.
  • --continue / -c: Reanuda directamente la sesión más reciente.

Técnicamente, ambos activan la reconstrucción del contexto y la etiqueta cache_control, por lo que las condiciones para activar el error son exactamente las mismas. Cualquier usuario de Bedrock puede encontrarse con este error 400 al usar ambos comandos.

Q6: ¿Seguiré teniendo este problema si uso LiteLLM como proxy para Bedrock?

Desde marzo de 2026 (PR #22867), LiteLLM incluye la función _remove_scope_from_cache_control, que elimina automáticamente el campo scope de las solicitudes enviadas a Bedrock y Azure AI. Si utilizas la última versión de LiteLLM como proxy de Bedrock, este problema debería estar resuelto automáticamente. No obstante, por seguridad, se recomienda configurar también CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Q7: ¿Existe una solución perfecta que no afecte a ninguna funcionalidad?

Para los usuarios de Bedrock, actualmente no existe una solución sin pérdidas. La primera opción (desactivar Beta) solo sacrifica la nueva función scope, lo cual tiene un impacto mínimo. Si deseas utilizar todas las funciones de Prompt Caching de Claude (incluido scope), debes usar la API nativa de Anthropic. Puedes acceder rápidamente a la API nativa a través de la plataforma APIYI (apiyi.com) sin las restricciones de compatibilidad de Bedrock.

Guía rápida de solución de errores para Claude Code en Bedrock

Acción Comando / Configuración
Opción 1: Deshabilitar Beta (recomendado) export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Opción 2: Deshabilitar caché export DISABLE_PROMPT_CACHING=1
Configuración en VS Code / JetBrains Editar el campo env en ~/.claude/settings.json
Verificar variables de entorno echo $CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
Probar reanudación de sesión claude --resume
Ver archivo de configuración cat ~/.claude/settings.json
Ver versión de Claude Code claude --version
Seguimiento en GitHub Issue anthropics/claude-code#23220

Resumen

Cuando utilizas Claude Code a través de AWS Bedrock, es posible que te encuentres con el error cache_control.scope: Extra inputs are not permitted. La causa raíz es que Bedrock no admite el campo scope de la API nativa de Anthropic, el cual es una función Beta.

La forma más rápida de solucionarlo:

# En la CLI
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

// En ~/.claude/settings.json (recomendado, funciona en todas las plataformas)
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Tres puntos clave a recordar:

  1. No es tu culpa: Se debe a las diferencias de funciones entre Bedrock y la API de Anthropic.
  2. Los usuarios de VS Code deben configurar el archivo settings.json: Las variables de entorno del shell no son leídas por la extensión de VS Code.
  3. --resume no es la causa raíz: Todas las invocaciones de Bedrock pueden activar este error; --resume simplemente hace que sea más fácil que aparezca.

Si no quieres lidiar con problemas de compatibilidad en Bedrock, cambiar a la API nativa de Anthropic es la solución definitiva. A través de APIYI (apiyi.com) puedes acceder rápidamente a la API nativa de Claude, con soporte completo para todas las funciones y sin necesidad de infraestructura de AWS.

Autor del artículo: Equipo técnico de APIYI
Intercambio técnico: Visita APIYI (apiyi.com) para obtener más tutoriales y soporte técnico sobre Claude Code.
Fecha de actualización: Abril de 2026
Versión aplicable: Claude Code v2.1.24+ y AWS Bedrock

Referencias:

  1. GitHub Issue #23220: Error de cache_control.scope en Claude Code v2.1.24+
    • Enlace: github.com/anthropics/claude-code/issues/23220
  2. GitHub Issue #41731: La extensión de VS Code envía un campo scope no soportado
    • Enlace: github.com/anthropics/claude-code/issues/41731
  3. Documentación de AWS Bedrock Prompt Caching:
    • Enlace: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
  4. Documentación de Anthropic Prompt Caching:
    • Enlace: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
  5. Documentación oficial de Claude Code en Amazon Bedrock:
    • Enlace: docs.anthropic.com/en/docs/claude-code/bedrock

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Publicaciones Similares