3 soluções para corrigir o erro de scope cache_control do Claude Code Bedrock: guia completo de solução de problemas para falhas na retomada de sessão com –resume

Se você encontrou este erro ao conectar o Claude Code ao 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

Isso acontece com frequência, especialmente ao usar --resume para retomar sessões anteriores — este é um problema de compatibilidade conhecido, não um erro na sua configuração.

A causa raiz é que o Claude Code envia um campo scope que o Bedrock não suporta. Você pode resolver isso definindo apenas uma variável de ambiente em 30 segundos.

Valor central: Ao terminar de ler este artigo, você entenderá a causa desse erro, dominará 3 soluções de correção e saberá como configurar corretamente em ambientes como CLI, VS Code e JetBrains.

Análise profunda do erro no Claude Code com Bedrock

Para entender esse erro, é preciso conhecer um contexto fundamental: o nível de suporte ao cache_control difere entre a API nativa da Anthropic e o AWS Bedrock.

A causa técnica do erro

Em janeiro de 2026, a Anthropic lançou uma funcionalidade Beta na API nativa chamada prompt-caching-scope-2026-01-05, que adicionou o campo scope ao objeto cache_control:

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

A partir da versão v2.1.24 do Claude Code, esse campo scope passou a ser incluído por padrão nas requisições da API.

O problema é: O AWS Bedrock não reconhece o campo scope, e a validação de esquema do Bedrock é extremamente rigorosa — qualquer campo desconhecido resulta diretamente em um erro 400.

Em resumo: a API nativa da Anthropic é mais tolerante e ignora campos que não conhece. O Bedrock é rigoroso e rejeita a requisição imediatamente. Como o Claude Code envia um campo que o Bedrock não conhece, o erro ocorre.

🎯 Dica técnica: Este problema afeta apenas usuários que utilizam o Claude via AWS Bedrock. Se você utiliza a API nativa da Anthropic (por exemplo, via plataforma APIYI apiyi.com), não encontrará esse erro, pois a API nativa oferece suporte completo ao campo scope.

Por que o Claude Code –resume é mais propenso a esse erro?

Embora esse erro não seja exclusivo do --resume, ele é mais frequente ao restaurar sessões históricas. Os motivos são:

Mecanismo interno do --resume:

1. Carregar sessão histórica: Lê o registro completo da conversa em ~/.claude/projects/<projeto>/<id_da_sessão>.jsonl.
2. Reconstruir contexto: Reagrupa o system prompt, definições de ferramentas e todas as mensagens históricas em um array de mensagens completo.
3. Otimização de cache: Como o contexto recuperado geralmente é grande, o Claude Code define pontos de interrupção de cache_control nas mensagens do sistema de forma mais agressiva para otimizar custos.
4. Enviar requisição: A primeira chamada da API já inclui o contexto reconstruído completo + cache_control (contendo o campo scope).

Ponto principal: Ao restaurar uma sessão, o contexto é maior → a otimização de cache é mais agressiva → o campo cache_control aparece com mais frequência → a probabilidade de disparar o erro é maior.

Iniciar uma nova sessão também pode causar o erro, mas como o contexto inicial é menor, as marcações de cache podem não ser tão densas.

Solução 1 para erro do Claude Code no Bedrock: Desativar Betas experimentais (Recomendado)

Esta é a solução mais recomendada — ela corrige o erro e, ao mesmo tempo, mantém a funcionalidade básica de Prompt Caching.

Princípio da solução

Ao definir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, o Claude Code fará o seguinte:

• Removerá os cabeçalhos Beta das solicitações (como prompt-caching-scope-2026-01-05)
• Removerá o campo scope dentro de cache_control
• Manterá campos suportados pelo Bedrock, como cache_control.type e cache_control.ttl

Ou seja, você ainda pode aproveitar a otimização de custos trazida pelo Prompt Caching, apenas sem usar o novo recurso de scope.

Configuração no terminal CLI

macOS / Linux:

# Configuração temporária (válida apenas para a sessão atual do terminal)
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Configuração permanente (adicionar ao arquivo de configuração do shell)
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.zshrc
source ~/.zshrc

# Se estiver usando bash
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

# Configuração temporária
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"

# Configuração permanente
[System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS", "1", "User")

Após configurar, basta executar o Claude Code:

# Iniciar nova sessão
claude

# Retomar sessão (agora sem erros)
claude --resume

Configuração da extensão do VS Code (Importante!)

A extensão do VS Code não lê variáveis de ambiente do shell — mesmo que você as tenha definido no .zshrc, a extensão do Claude Code no VS Code não as reconhecerá. Você deve configurá-las da seguinte forma:

Método 1: Editar o arquivo de configuração global do Claude (Recomendado)

Edite o arquivo ~/.claude/settings.json:

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

Método 2: Via configurações do VS Code

Abra as configurações do VS Code → pesquise por claude → encontre a opção de configuração de variáveis de ambiente → adicione CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Configuração para IDEs JetBrains

O plugin do Claude Code nas IDEs da família JetBrains (IntelliJ, WebStorm, PyCharm, etc.) também precisa de uma configuração separada:

Edite o arquivo ~/.claude/settings.json (o mesmo arquivo compartilhado com o VS Code):

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

💡 Dica: O arquivo ~/.claude/settings.json é o arquivo de configuração global do Claude Code, e todos os clientes (CLI, VS Code, JetBrains) o leem. Configurar as variáveis de ambiente aqui é a maneira mais prática, garantindo que funcione em todas as plataformas com apenas um ajuste.

Solução 2 para erro do Claude Code no Bedrock: Desativar Prompt Caching

Se a Solução 1 ainda não resolver o seu problema (em casos raros), você pode desativar completamente o Prompt Caching.

Princípio da solução

Ao definir DISABLE_PROMPT_CACHING=1, o Claude Code removerá todos os campos cache_control das solicitações. Sem o cache_control, não haverá o campo scope e o erro desaparecerá completamente.

Custo: Perda da otimização de custos trazida pelo Prompt Caching. Para conversas longas, isso pode significar taxas de tokens mais altas.

Como configurar

# CLI
export DISABLE_PROMPT_CACHING=1

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

Quando escolher a Solução 2?

Solução de Erro 3 para Claude Code Bedrock: Configuração de Segurança Dupla

Defina ambos os ambientes simultaneamente para garantir que todos os campos não suportados pelo Bedrock sejam removidos.

# 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 é a configuração mais segura, ideal para cenários em produção que exigem estabilidade absoluta.

🚀 Outra abordagem: Se você não quer lidar com variáveis de ambiente ou se preocupar com problemas de compatibilidade do Bedrock, considere mudar para a API nativa da Anthropic. Através da plataforma APIYI (apiyi.com), você pode acessar diretamente as interfaces nativas da Anthropic, com suporte completo a todas as funcionalidades de Prompt Caching (incluindo scope), sem a necessidade de uma conta AWS.

Fluxo Completo de Diagnóstico de Erros do Claude Code Bedrock

Se você não tem certeza de qual solução se aplica ao seu caso, siga este fluxo de diagnóstico:

Passo 1: Confirme o tipo de erro

Verifique se a mensagem de erro contém as seguintes palavras-chave:

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

ou

ValidationException: ... cache_control ... scope

Se sim, isso indica um problema de compatibilidade com o campo scope.

Passo 2: Confirme o caminho de invocação

# Verifique o endpoint da API que o Claude Code está usando
echo $ANTHROPIC_BASE_URL
echo $CLAUDE_CODE_USE_BEDROCK

Se você definiu CLAUDE_CODE_USE_BEDROCK=1 ou variáveis relacionadas ao Bedrock como AWS_REGION, significa que você está usando o Bedrock.

Passo 3: Aplique a correção

# Tente a primeira solução
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# Teste se o erro foi corrigido
claude --resume

Passo 4: Valide a correção

# Verifique se a variável de ambiente entrou em vigor
echo $CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
# Deve exibir: 1

# Teste criando uma nova sessão
claude

# Teste retomando uma sessão
claude --resume

Passo 5: Se o erro persistir

# Adicione a segunda solução
export DISABLE_PROMPT_CACHING=1

# Verifique também o settings.json
cat ~/.claude/settings.json

Certifique-se de que o formato do settings.json esteja correto:

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

🎯 Dica técnica: Se você utiliza um serviço proxy de API como o LiteLLM para conectar ao Bedrock, o LiteLLM já possui, desde março de 2026, a funcionalidade de remoção automática do campo scope (PR #22867). Atualizar para a versão mais recente do LiteLLM também resolve este problema. Se você busca uma solução de acesso à API do Claude mais estável, a APIYI (apiyi.com) oferece canais nativos da API Anthropic, que não sofrem com esse tipo de restrição de compatibilidade.

Outros problemas comuns de compatibilidade do Claude Code com Bedrock

O cache_control.scope não é o único obstáculo de compatibilidade do Bedrock. Aqui estão outros problemas semelhantes que os usuários do Bedrock costumam encontrar:

A maioria dos problemas pode ser resolvida de forma definitiva com CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, já que esses campos sem suporte são, essencialmente, recursos Beta da API nativa da Anthropic.

💰 Otimização de custos: O Prompt Caching do Bedrock suporta apenas TTLs de 5 minutos e 1 hora. Se o seu cenário de uso depende muito de cache, acessar a API nativa da Anthropic via APIYI (apiyi.com) permite estratégias de cache mais flexíveis, evitando os custos de depuração causados pelos problemas de compatibilidade mencionados acima.

FAQ: Problemas comuns de erro do Claude Code com Bedrock

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

Guia de Resolução de Erros: Claude Code com Bedrock

Resumo

Ao utilizar o Claude Code via AWS Bedrock, você pode encontrar o erro cache_control.scope: Extra inputs are not permitted. A causa raiz é que o Bedrock não oferece suporte ao campo scope (Beta) da API nativa da Anthropic.

A forma mais rápida de corrigir:

# No CLI
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

// No ~/.claude/settings.json (Recomendado, funciona em todas as plataformas)
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Três pontos para lembrar:

1. O problema não é seu — trata-se de uma diferença de funcionalidades entre o Bedrock e a API da Anthropic.
2. Usuários do VS Code devem configurar via settings.json — variáveis de ambiente do shell não são lidas pela extensão do VS Code.
3. --resume não é a causa raiz — todas as invocações do modelo via Bedrock podem disparar o erro; o --resume apenas torna a falha mais evidente.

Se você não quer lidar com problemas de compatibilidade do Bedrock, mudar para a API nativa da Anthropic é a solução definitiva. Através da APIYI (apiyi.com), você pode acessar a API nativa do Claude rapidamente, com suporte completo a todos os recursos, sem depender da infraestrutura da AWS.

Autor do artigo: Equipe técnica da APIYI
Troca de conhecimentos: Acesse APIYI (apiyi.com) para mais tutoriais e suporte técnico sobre o Claude Code
Data de atualização: Abril de 2026
Versões aplicáveis: Claude Code v2.1.24+, AWS Bedrock

Referências:

1. GitHub Issue #23220: Erro cache_control.scope no Claude Code v2.1.24+
   • Link: github.com/anthropics/claude-code/issues/23220
2. GitHub Issue #41731: Extensão do VS Code envia campo scope não suportado
   • Link: github.com/anthropics/claude-code/issues/41731
3. Documentação do Prompt Caching no AWS Bedrock:
   • Link: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
4. Documentação do Prompt Caching da Anthropic:
   • Link: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
5. Documentação oficial do Claude Code no Amazon Bedrock:
   • Link: docs.anthropic.com/en/docs/claude-code/bedrock