---
title: Errori della Claude API
url: https://platform.claude.com/docs/it/api/errors
description: Comprendi i codici di stato HTTP, la struttura delle risposte di errore e gli ID delle richieste restituiti dalla Claude API, e gestisci gli errori con le eccezioni tipizzate dell'SDK.
---

## Errori HTTP

L’API segue un formato prevedibile per i codici di errore HTTP:

* 400 - `invalid_request_error`: C’è un problema con il formato o il contenuto della tua richiesta. L’API potrebbe anche usare questo tipo di errore per altri codici di stato 4XX non elencati in questa sezione. L’API restituisce un 400 anche quando l’utilizzo raggiunge un [“spend limit” (limite di spesa) impostato da te](https://platform.claude.com/docs/it/api/rate-limits#setting-your-own-spend-limit) per un’organizzazione o un workspace. I limiti sul [workspace di Claude Code](https://platform.claude.com/docs/it/manage-claude/workspaces#claude-code-workspace) sono l’eccezione: possono invece restituire un 429. Se il messaggio indica un problema con la tua richiesta, cercalo in [Errori di validazione comuni](https://platform.claude.com/docs/it/api/errors#common-validation-errors).

* 401 - `authentication_error`: C’è un problema con la tua [chiave API](https://platform.claude.com/docs/it/get-api-key) (ad esempio, è malformata, revocata o scaduta; consulta [Scadenza della chiave](https://platform.claude.com/docs/it/manage-claude/authentication#key-expiration)). Su Claude Platform on AWS, questo può indicare anche un problema con le tue credenziali AWS o con la firma SigV4.

  Un 401 il cui messaggio inizia con `CORS requests are not allowed for this Organization` non è un problema della tua chiave API. La richiesta includeva un header `Origin`, che i browser aggiungono, e la tua organizzazione non può chiamare la Claude API direttamente da un browser. Il messaggio prosegue con `because of custom retention settings` oppure `because of its settings`. Il primo compare solo per accordi di conservazione dei dati come la “zero data retention” (conservazione zero dei dati), o ZDR; il secondo è il caso generale, che include la Compliance API. Nessuna modifica alla richiesta del browser risolve il problema, quindi invia la richiesta dal tuo back end; consulta [Applicazioni basate su browser](https://platform.claude.com/docs/it/manage-claude/authentication#browser-based-applications).

* 402 - `billing_error`: C’è un problema con le tue informazioni di fatturazione o di pagamento. Controlla i tuoi dati di pagamento nella [Claude Console](https://platform.claude.com), oppure in AWS Marketplace se utilizzi Claude Platform on AWS.

* 403 - `permission_error`: La tua chiave API non ha l’autorizzazione per utilizzare la risorsa specificata. Controlla le impostazioni di accesso e dei workspace della tua organizzazione nella [Claude Console](https://platform.claude.com).

* 404 - `not_found_error`: La risorsa richiesta non è stata trovata. Controlla il percorso dell’endpoint e gli eventuali ID delle risorse nell’URL della richiesta.

* 409 - `conflict_error`: La richiesta è in conflitto con lo stato attuale di una risorsa. Ad esempio, la risorsa è stata modificata contemporaneamente, oppure un valore che deve essere univoco è già in uso. Risolvi il conflitto, quindi riprova la richiesta.

* 413 - `request_too_large`: La richiesta supera il numero massimo di byte consentito. Consulta [Limiti di dimensione delle richieste](https://platform.claude.com/docs/it/api/errors#request-size-limits) per i valori massimi per endpoint.

* 429 - `rate_limit_error`: La tua organizzazione ha raggiunto un [“rate limit” (limite di velocità)](https://platform.claude.com/docs/it/api/rate-limits), ha raggiunto il tetto di spesa mensile del suo livello di utilizzo, oppure ha raggiunto un limite di spesa sul workspace di Claude Code. Un 429 dovuto al tetto di spesa del livello non ha l’header `retry-after` e continua a fallire finché l’accesso non riprende; consulta [Raggiungimento del tetto di spesa](https://platform.claude.com/docs/it/api/rate-limits#reaching-your-spend-cap) per sapere come riconoscerlo. Un forte aumento dell’utilizzo può causare un 429 anche quando sei al di sotto dei tuoi limiti di velocità; consulta [“Ramp limits” (limiti di crescita)](https://platform.claude.com/docs/it/api/rate-limits#ramp-limits).

* 500 - `api_error`: Si è verificato un errore imprevisto interno ai sistemi di Anthropic. Riprova la richiesta con “exponential backoff” (backoff esponenziale); se l’errore persiste, contatta il supporto indicando il [“request ID” (ID della richiesta)](https://platform.claude.com/docs/it/api/errors#request-id). Se invece il tipo di errore è `timeout_error`, consulta la voce 504.

* 504 - `timeout_error`: La richiesta è scaduta durante l’elaborazione. L’API restituisce `timeout_error` anche con altri codici di stato, ad esempio un 500 quando una richiesta raggiunge il limite di tempo del server prima che la risposta inizi. Per le richieste di lunga durata alla Messages API, usa la [Messages API in streaming](https://platform.claude.com/docs/it/build-with-claude/streaming). Consulta [Richieste lunghe](https://platform.claude.com/docs/it/api/errors#long-requests) per ulteriori opzioni.

* 529 - `overloaded_error`: L’API è temporaneamente sovraccarica.

  <Warning>
    Un errore 529 può verificarsi quando l’API registra un traffico elevato da parte di tutti gli utenti.
  </Warning>

L’SDK ufficiale ritenta automaticamente le richieste in caso di errori transitori (come errori di connessione, limiti di velocità ed errori del server 5xx) con backoff esponenziale, due volte per impostazione predefinita, rispettando l’header `retry-after` quando presente. Il client dell’SDK accetta `max_retries` (typescript, php: `maxRetries`; java: `.maxRetries()`; csharp: `MaxRetries`; go: `option.WithMaxRetries()`) per configurare o disabilitare questo comportamento.

Quando ricevi una risposta in [streaming](https://platform.claude.com/docs/it/build-with-claude/streaming) tramite “server-sent events” (eventi inviati dal server), o SSE, può verificarsi un errore dopo che l’API ha restituito una risposta 200. In tal caso, la gestione degli errori non segue questi meccanismi standard. Consulta [Eventi di errore](https://platform.claude.com/docs/it/build-with-claude/streaming#error-events) per la struttura degli errori che si verificano durante lo stream.

## Limiti di dimensione delle richieste

La Claude API di prima parte applica questi limiti di dimensione delle richieste. Per altre piattaforme, consulta la [panoramica dell’API](https://platform.claude.com/docs/it/api/overview#request-size-limits).

| Tipo di endpoint                                                                    | Dimensione massima della richiesta |
| ----------------------------------------------------------------------------------- | ---------------------------------- |
| Messages API                                                                        | 128 MB                             |
| Token Counting API                                                                  | 128 MB                             |
| [Batch API](https://platform.claude.com/docs/it/build-with-claude/batch-processing) | 256 MB                             |
| [Files API](https://platform.claude.com/docs/it/build-with-claude/files)            | 500 MB                             |

Se superi questi limiti, riceverai un errore 413 `request_too_large`. Sulla Claude API di prima parte, Cloudflare restituisce questo errore prima che la richiesta raggiunga i server dell’API.

## Struttura degli errori

L’API restituisce sempre gli errori come JSON, con un oggetto `error` di primo livello che include sempre un valore `type` e un valore `message`. La risposta include anche un campo `request_id` per facilitare il tracciamento e il debug. Ad esempio:

```json JSON
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
```

In base alla [politica di versionamento dell’API](https://platform.claude.com/docs/it/api/versioning), i valori all’interno di questi oggetti possono espandersi e possono comparire nuovi valori di `type`.

## Tipi di errore dell’SDK

L’SDK ufficiale solleva eccezioni tipizzate per questi errori invece di restituire JSON grezzo. Ad esempio, un 404 si presenta come `anthropic.NotFoundError` (typescript: `Anthropic.NotFoundError`; ruby: `Anthropic::Errors::NotFoundError`; java: `com.anthropic.errors.NotFoundException`; csharp: `AnthropicNotFoundException`; php: `Anthropic\Core\Exceptions\NotFoundException`; go: `*anthropic.Error`). L’SDK Go usa un unico tipo di errore per tutti gli stati, `*anthropic.Error`: usa `StatusCode` per distinguere i casi. Intercetta le classi tipizzate dell’SDK invece di confrontare le stringhe dei messaggi di errore, gestendo prima le classi più specifiche. La pagina del tuo SDK documenta la gerarchia completa delle eccezioni:

* [Python](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/ruby#handling-errors)

## ID della richiesta

Ogni risposta dell’API include un header `request-id` univoco. Questo header contiene un valore come `req_018EeWyXxfu5pfWkrYcMdjWG`. Lo stesso identificatore compare come campo `request_id` nei [corpi delle risposte di errore](https://platform.claude.com/docs/it/api/errors#error-shapes). Quando contatti il supporto riguardo a una richiesta specifica, includi questo ID per aiutare a risolvere rapidamente il problema.

Su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), le risposte includono due ID di richiesta: l’ID di richiesta AWS (`x-amzn-requestid`, primario, indicizzato in CloudTrail) e l’ID di richiesta Anthropic (`request-id`, secondario). Usa l’ID di richiesta AWS per le ricerche in CloudTrail e l’ID di richiesta Anthropic per i ticket di supporto Anthropic.

Gli SDK Python e TypeScript espongono l’ID della richiesta come proprietà `_request_id` sugli oggetti di risposta di primo livello. Gli SDK C#, Go, Java e PHP lo espongono tramite i loro accessor per la risposta grezza, e l’SDK Ruby tramite [middleware](https://platform.claude.com/docs/it/cli-sdks-libraries/middleware). In tutti gli SDK tranne Ruby, usa `with_raw_response` (typescript: `.withResponse()`; java: `.withRawResponse()`; csharp: `WithRawResponse`; go: `option.WithResponseInto()`; php: `->raw`) per leggere qualsiasi altro [header di risposta](https://platform.claude.com/docs/it/api/overview#response-headers), come `anthropic-organization-id` e [`anthropic-workspace-id`](https://platform.claude.com/docs/it/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). In Ruby, usa lo stesso middleware. Su Claude Platform on AWS, usa l’accessor alla risposta grezza anche per leggere l’ID di richiesta AWS (`x-amzn-requestid`):

<CodeGroup>
  ```bash cURL
  # -i stampa gli header della risposta, incluso request-id, prima del corpo
  curl -sS -i https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}]
    }'
  ```

  ```bash CLI
  # L'header request-id viene stampato su 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 UserMessageParam { 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<Message> 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

  # Leggi gli header della risposta nel middleware per richiesta, che riceve la
  # risposta HTTP grezza prima che l'SDK la analizzi
  request_id = nil
  read_request_id = lambda do |request, call_next|
    response = call_next.call(request)
    # Le chiavi in response.headers sono in minuscolo
    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);
  ```
</CodeGroup>

Per esempi di ID di richiesta di Claude Platform on AWS in altri linguaggi, consulta [ID delle richieste](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#request-ids).

## Richieste lunghe

<Warning>
  Valuta l’uso della [Messages API in streaming](https://platform.claude.com/docs/it/build-with-claude/streaming) o della [Message Batches API](https://platform.claude.com/docs/it/api/messages/batches/create) per le richieste di lunga durata, in particolare quelle superiori a 10 minuti.
</Warning>

Evita di impostare un valore elevato di `max_tokens` senza utilizzare la [Messages API in streaming](https://platform.claude.com/docs/it/build-with-claude/streaming) o la [Message Batches API](https://platform.claude.com/docs/it/api/messages/batches/create):

* Alcune reti potrebbero interrompere le connessioni inattive dopo un periodo di tempo variabile, il che può causare il fallimento o il timeout della richiesta senza ricevere una risposta da Anthropic.
* Le reti differiscono in termini di affidabilità. La [Message Batches API](https://platform.claude.com/docs/it/api/messages/batches/create) può aiutarti a gestire il rischio di problemi di rete consentendoti di interrogare periodicamente i risultati invece di richiedere una connessione di rete ininterrotta.

Se stai realizzando un’integrazione diretta con l’API, impostare un [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html) può ridurre l’impatto dei timeout delle connessioni inattive su alcune reti.

L’[Anthropic SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) verifica che le tue richieste non in streaming alla Messages API non debbano superare un timeout di 10 minuti. Imposta inoltre un’opzione del socket per il TCP keep-alive.

Se non hai bisogno di elaborare gli eventi in modo incrementale, l’SDK può consumare lo stream per te e restituire l’oggetto `Message` completo, identico a quello restituito da una chiamata non in streaming:

<CodeGroup exclude="shell:cURL">
  <CodeGroupItem language="cURL">
    Una richiesta curl stampa gli eventi grezzi dello stream e non può combinarli nel messaggio finale. Per ottenere l’oggetto `Message` completo da uno stream, usa l’[Anthropic SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview).
  </CodeGroupItem>

  ```bash CLI
  # La CLI trasmette gli eventi in streaming; --format jsonl emette un evento per riga
  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 UserMessageParam { 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: Anthropic::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
  ```
</CodeGroup>

Consulta [Ottenere il messaggio finale senza gestire gli eventi](https://platform.claude.com/docs/it/build-with-claude/streaming#get-the-final-message-without-handling-events) per maggiori dettagli.

## Errori di validazione comuni

### Prefill non supportato

I modelli Claude 4.6 e successivi e [Claude Mythos Preview](https://anthropic.com/glasswing) non supportano il “prefill” (precompilazione) dei messaggi dell’assistente. L’invio a uno qualsiasi di questi modelli di una richiesta con un ultimo messaggio dell’assistente precompilato restituisce 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."
  }
}
```

Usa invece gli [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) sui modelli che li supportano, istruzioni nel prompt di sistema oppure [`output_config.format`](https://platform.claude.com/docs/it/build-with-claude/structured-outputs#usage).

### I blocchi di ragionamento non possono essere modificati

Se i blocchi di ragionamento nella richiesta non corrispondono a quanto restituito dall’API, la richiesta può ricevere un 400 `invalid_request_error`. Il messaggio di errore inizia con la posizione del blocco incriminato (ad esempio, `messages.1.content.0`) e 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 il “tool use” (uso degli strumenti), rinvia ogni blocco `thinking` e `redacted_thinking` del turno dell’assistente esattamente come ricevuto, inclusi i blocchi il cui campo `thinking` è vuoto. Se la tua applicazione filtra i blocchi di contenuto per tipo prima di rinviarli, includi sia `thinking` sia `redacted_thinking`. Si tratta di un errore diverso da quello del [“prefix check” (controllo del prefisso)](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking/prefix-checks#prefix-check), il cui errore indica che un blocco è vincolato a una conversazione diversa. Impostare `prefix_mismatch_behavior` potrebbe non risolverlo. Consulta la [correzione per i blocchi di ragionamento modificati](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) in Risoluzione dei problemi del ragionamento.

### Ragionamento esteso non supportato

I modelli Claude 4.7 e successivi non supportano l’“extended thinking” (ragionamento esteso). L’invio di `thinking: {"type": "enabled"}` a uno qualsiasi di questi modelli restituisce 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.
```

Usa invece il [ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/thinking). Per la mappatura dei parametri, consulta [Migrazione al ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/extended-thinking#migrating-to-adaptive-thinking). Per correggere l’errore a partire dal sintomo, consulta [Un errore 400 indica che `"thinking.type.enabled"` non è supportato](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled).

### Ragionamento adattivo non supportato

I modelli che supportano solo il ragionamento esteso (Claude 4.5 e modelli precedenti) rifiutano `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}` su questi modelli; consulta [Ragionamento esteso](https://platform.claude.com/docs/it/build-with-claude/extended-thinking) per la configurazione e la [correzione basata sui sintomi per l’errore del ragionamento adattivo](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive) in Risoluzione dei problemi del ragionamento.

### Il ragionamento non può essere disabilitato

Su Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/it/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview), Claude Opus 5.5 e [Claude Mythos Preview](https://anthropic.com/glasswing), il ragionamento è sempre attivo. L’invio di `thinking: {"type": "disabled"}` a uno qualsiasi di questi modelli restituisce un 400 `invalid_request_error`. Su tutti questi modelli tranne Claude Mythos Preview, il messaggio riporta:

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

Su Claude Mythos Preview, l’unico di questi modelli che accetta il ragionamento esteso, il messaggio riporta:

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

Su Claude Sonnet 5.5, il ragionamento non può essere impostato su `disabled`. Usa `thinking: {"type": "between_tools"}` per l’impostazione di ragionamento più bassa, che disattiva il ragionamento iniziale. L’invio di `thinking: {"type": "disabled"}` restituisce un 400 `invalid_request_error` con questo messaggio:

```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 [effort](https://platform.claude.com/docs/it/build-with-claude/effort) `xhigh` o `max`, anche una richiesta con `between_tools` restituisce un 400 `invalid_request_error`. Il messaggio di errore indica che il ragionamento è disabilitato perché `between_tools` non prevede ragionamento iniziale:

```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`, l’effort non può cambiare a metà conversazione: un `output_config.effort` per singolo messaggio diverso dal livello in vigore restituisce un errore 400. L’errore indica la posizione del messaggio che ha impostato il nuovo livello:

```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 accetta `thinking: {"type": "disabled"}` e lo sottopone agli stessi due limiti di effort che si applicano a `between_tools`: con effort `xhigh` o `max`, oppure con un `output_config.effort` per messaggio diverso dal livello in vigore, la richiesta restituisce un 400 `invalid_request_error` con il messaggio corrispondente mostrato in precedenza.

In entrambi i messaggi, “enable thinking” si riferisce al ragionamento adattivo: ometti il campo `thinking` oppure invia `thinking: {"type": "adaptive"}`. Anche Claude Sonnet 5.5 e Claude Haiku 5.5 rifiutano `"enabled"` con un errore 400. Per variare l’effort a ogni turno, usa il ragionamento adattivo.

L’invio di `thinking: {"type": "between_tools"}` a qualsiasi modello diverso da Claude Sonnet 5.5 restituisce un 400 `invalid_request_error`:

```text wrap
"thinking.type.between_tools" is not supported for this model.
```

Per le correzioni, consulta gli [errori di `between_tools` e di effort](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools) in Risoluzione dei problemi del ragionamento.

Se ometti il parametro `thinking`, la richiesta viene eseguita con il ragionamento adattivo. Per escludere il contenuto del ragionamento dalle risposte senza disattivare il ragionamento, imposta `display: "omitted"` nella configurazione del ragionamento. Consulta la [correzione per l’errore del ragionamento disabilitato](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled) in Risoluzione dei problemi del ragionamento.

### Uso forzato degli strumenti non supportato

Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/it/models/mythos-5-2/overview), Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview) non supportano l’uso forzato degli strumenti. L’invio di `tool_choice: {"type": "any"}` o `tool_choice: {"type": "tool", "name": "..."}` a uno qualsiasi di questi modelli, anche sull’[endpoint di conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting), restituisce un 400 `invalid_request_error`:

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

`tool_choice: {"type": "auto"}` (il valore predefinito) e `{"type": "none"}` sono accettati. Usa `auto` con l’[uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use) per mantenere gli input degli strumenti conformi allo schema, oppure gli [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) quando hai bisogno che la risposta stessa abbia una struttura JSON fissa. Consulta [Forzare l’uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools#forcing-tool-use).

### Versione dello strumento computer use non supportata

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 restituiscono un errore 400 per qualsiasi versione dello strumento di [computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool) che non accettano. Sull’API Claude, ciò include `computer_20251124` con il relativo header beta. Non accettano `computer_20250124` su nessuna piattaforma. Il messaggio `invalid_request_error` dell’API Claude indica il tipo rifiutato e, dopo `Did you mean one of`, elenca i tipi di strumento accettati dal modello. Per Claude Opus 5.5, il messaggio inizia così:

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

L’API Claude restituisce lo stesso messaggio per qualsiasi tipo di strumento definito da Anthropic che il modello richiesto non supporta. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 supportano il computer use tramite il toolset `computer_toolset_20260801`. Dichiara `{"type": "computer_toolset_20260801"}` senza l’header beta e aggiorna il ciclo del tuo agente come descritto in [Migrare da `computer_20251124`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Per passare da `computer_20250124`, consulta [Spostare il computer use sul toolset](https://platform.claude.com/docs/it/models/haiku-5-5/migration-guide#computer-use-toolset) nella guida alla migrazione di Claude Haiku 5.5.

Su Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 accettano anche lo strumento `computer_20251124` con l’header beta `computer-use-2025-11-24`. Con l’API InvokeModel di Amazon Bedrock, invia `computer-use-2025-11-24` nell’array `anthropic_beta` del corpo della richiesta invece che in un header. Per quell’API, consulta [Claude su Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy). Per i modelli da usare con ciascuna versione precedente, consulta [Versioni precedenti dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).

### Blocco di ragionamento associato a una conversazione diversa

Questo errore 400 `invalid_request_error` significa che un blocco di ragionamento che hai rinviato non ha superato il [controllo del prefisso](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking/prefix-checks#prefix-check). Confronta `system`, `tools` e i messaggi prima del blocco con ciò che hai inviato quando il modello lo ha prodotto. Per sapere quali modifiche contano, consulta [Cosa conta come modifica](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking/prefix-checks#what-counts-as-an-edit). Il messaggio di errore inizia con la posizione del primo blocco che non supera il controllo del prefisso:

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

Reinviare la stessa cronologia fallisce allo stesso modo. Correggere il codice che ha apportato la modifica non aiuta questa conversazione se la modifica è ancora nella sua cronologia. Per continuare, esegui una delle seguenti operazioni:

* Invia l’header beta `thinking-binding-controls-2026-08-01` e imposta `thinking.block_binding.prefix_mismatch_behavior` su `"drop_block"`, nel nuovo tentativo e in ogni richiesta successiva di quella conversazione. Su Claude Sonnet 5.5 e Claude Haiku 5.5, `block_binding` funziona solo con `thinking: {"type": "adaptive"}`.
* Rimuovi il blocco indicato dall’errore e ogni blocco `thinking` e `redacted_thinking` successivo, in quel messaggio e in ogni messaggio successivo. Riprova, e lascia fuori i blocchi rimossi dalle richieste successive.

Per evitare che le nuove conversazioni falliscano, [mantieni la cronologia in sola aggiunta](https://platform.claude.com/docs/it/build-with-claude/preserved-thinking/prefix-checks#what-to-check). Consulta la [soluzione per una firma del blocco di ragionamento non valida](https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting#error-thinking-block-signature) in Risoluzione dei problemi del ragionamento.

L’invio di `thinking.block_binding` senza l’[header beta](https://platform.claude.com/docs/it/api/beta-headers) `thinking-binding-controls-2026-08-01` restituisce un 400 `invalid_request_error` il cui messaggio termina con:

```text wrap
block_binding: Extra inputs are not permitted
```

Aggiungi l’header, attiva il ragionamento oppure rimuovi il campo.

### Federazione dell’identità web in uscita disabilitata (Claude Platform on AWS)

Se ogni richiesta a [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws) restituisce `"Outbound web identity federation is disabled for your account"`, esegui `aws iam enable-outbound-web-identity-federation` una volta per ciascun account AWS. Consulta [Abilitare la federazione dell’identità web in uscita](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) per i dettagli.

## Passaggi successivi

<CardGroup cols={3}>
  <Card title="Risoluzione dei problemi del ragionamento" icon="wrench" href="https://platform.claude.com/docs/it/build-with-claude/thinking-troubleshooting">
    Soluzioni a partire dal sintomo per gli errori 400 di configurazione del ragionamento, i blocchi di ragionamento vuoti e le interruzioni per `max_tokens`.
  </Card>

  <Card title="Limiti di velocità" icon="gauge" href="https://platform.claude.com/docs/it/api/rate-limits">
    Per mitigare gli abusi e gestire la capacità dell’API, sono previsti limiti su quanto un’organizzazione può utilizzare la Claude API.
  </Card>

  <Card title="Messaggi in streaming" icon="lightning" href="https://platform.claude.com/docs/it/build-with-claude/streaming">
    Ricevi in streaming le risposte della Messages API in modo incrementale con server-sent events, inclusi testo, uso degli strumenti e delta del ragionamento esteso.
  </Card>
</CardGroup>
