Claude Platform Docs
Riferimento APIUtilizzo dell'API

Errori della Claude API

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 per un’organizzazione o un workspace. I limiti sul workspace di Claude Code sono l’eccezione: possono invece restituire un 429. Se il messaggio indica un problema con la tua richiesta, cercalo in Errori di validazione comuni.

  • 401 - authentication_error: C’è un problema con la tua chiave API (ad esempio, è malformata, revocata o scaduta; consulta Scadenza della chiave). 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.

  • 402 - billing_error: C’è un problema con le tue informazioni di fatturazione o di pagamento. Controlla i tuoi dati di pagamento nella Claude Console, 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.

  • 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 per i valori massimi per endpoint.

  • 429 - rate_limit_error: La tua organizzazione ha raggiunto un “rate limit” (limite di velocità), 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 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).

  • 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). 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. Consulta Richieste lunghe per ulteriori opzioni.

  • 529 - overloaded_error: L’API è temporaneamente sovraccarica.

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 per configurare o disabilitare questo comportamento.

Quando ricevi una risposta in 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 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.

Tipo di endpointDimensione massima della richiesta
Messages API128 MB
Token Counting API128 MB
Batch API256 MB
Files API500 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
{
  "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, 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. 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:

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. Quando contatti il supporto riguardo a una richiesta specifica, includi questo ID per aiutare a risolvere rapidamente il problema.

Su 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. In tutti gli SDK tranne Ruby, usa with_raw_response per leggere qualsiasi altro header di risposta, come anthropic-organization-id e anthropic-workspace-id. 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):

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}")

Per esempi di ID di richiesta di Claude Platform on AWS in altri linguaggi, consulta ID delle richieste.

Richieste lunghe

Evita di impostare un valore elevato di max_tokens senza utilizzare la Messages API in streaming o la Message Batches APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro):

  • 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 APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) 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 può ridurre l’impatto dei timeout delle connessioni inattive su alcune reti.

L’Anthropic SDK 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:

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

Consulta Ottenere il messaggio finale senza gestire gli eventi per maggiori dettagli.

Errori di validazione comuni

Prefill non supportato

I modelli Claude 4.6 e successivi e Claude Mythos Preview 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:

{
  "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 sui modelli che li supportano, istruzioni nel prompt di sistema oppure output_config.format.

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:

`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), 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 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:

"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. Per la mappatura dei parametri, consulta Migrazione al ragionamento adattivo. Per correggere l’errore a partire dal sintomo, consulta Un errore 400 indica che "thinking.type.enabled" non è supportato.

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:

adaptive thinking is not supported on this model

Usa thinking: {"type": "enabled", "budget_tokens": N} su questi modelli; consulta Ragionamento esteso per la configurazione e la correzione basata sui sintomi per l’errore del ragionamento adattivo in Risoluzione dei problemi del ragionamento.

Il ragionamento non può essere disabilitato

Su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 e Claude Mythos Preview, 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:

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

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

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

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:

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:

"thinking.type.between_tools" is not supported for this model.

Per le correzioni, consulta gli errori di between_tools e di effort 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 in Risoluzione dei problemi del ragionamento.

Uso forzato degli strumenti non supportato

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 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, restituisce un 400 invalid_request_error:

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 per mantenere gli input degli strumenti conformi allo schema, oppure gli output strutturati quando hai bisogno che la risposta stessa abbia una struttura JSON fissa. Consulta Forzare l’uso degli strumenti.

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

'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. Per passare da computer_20250124, consulta Spostare il computer use sul 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). Per i modelli da usare con ciascuna versione precedente, consulta Versioni precedenti dello strumento.

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. 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. Il messaggio di errore inizia con la posizione del primo blocco che non supera il controllo del prefisso:

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. Consulta la soluzione per una firma del blocco di ragionamento non valida in Risoluzione dei problemi del ragionamento.

L’invio di thinking.block_binding senza l’header beta thinking-binding-controls-2026-08-01 restituisce un 400 invalid_request_error il cui messaggio termina con:

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 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 per i dettagli.

Passaggi successivi

Soluzioni a partire dal sintomo per gli errori 400 di configurazione del ragionamento, i blocchi di ragionamento vuoti e le interruzioni per max_tokens.

Per mitigare gli abusi e gestire la capacità dell’API, sono previsti limiti su quanto un’organizzazione può utilizzare la Claude API.

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.

Questa pagina ti è stata utile?