Errori della Claude API

Errori HTTP

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

• 400 - invalid_request_error: si è verificato un problema con il formato o il contenuto della tua richiesta. Questo tipo di errore può essere usato anche 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 l'organizzazione o il workspace. Fanno eccezione i limiti sul workspace Claude Code, che possono invece restituire un 429.

• 401 - authentication_error: c'è un problema con la tua chiave API (ad esempio, è malformata, revocata o scaduta; consulta Scadenza delle chiavi). Su Claude Platform on AWS, può anche indicare un problema con le tue credenziali AWS o con la firma SigV4.

• 402 - billing_error: c'è un problema con le tue informazioni di fatturazione o di pagamento. Controlla i dettagli di pagamento nella Claude Console, oppure in AWS Marketplace se usi Claude Platform on AWS.

• 403 - permission_error: la tua chiave API non ha l'autorizzazione per usare la risorsa specificata. Controlla l'accesso della tua organizzazione e le impostazioni del workspace nella Claude Console.

• 404 - not_found_error: la risorsa richiesta non è stata trovata. Controlla il percorso dell'endpoint e gli eventuali ID di risorsa 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 di ciascun endpoint.

• 429 - rate_limit_error: la tua organizzazione ha raggiunto un "rate limit" (limite di velocità), ha raggiunto il tetto di spesa mensile del proprio livello di utilizzo oppure ha raggiunto un limite di spesa sul workspace Claude Code. Un 429 dovuto al tetto di spesa del livello non include l'header retry-after e continua a fallire finché l'accesso non riprende; per sapere come riconoscerlo, consulta Raggiungimento del tetto di spesa.

• 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).

• 504 - timeout_error: la richiesta è scaduta durante l'elaborazione. Per le richieste di lunga durata, valuta l'uso della Messages API in streaming. Consulta Richieste lunghe per ulteriori opzioni.

• 529 - overloaded_error: l'API è temporaneamente sovraccarica.

Gli SDK ufficiali ritentano automaticamente le richieste in caso di errori transitori, come errori di connessione, limiti di velocità ed errori server 5xx. Usano il backoff esponenziale, eseguono due nuovi tentativi per impostazione predefinita e rispettano l'header retry-after quando presente. Per configurare o disabilitare questo comportamento, il client SDK accetta max_retries.

Quando ricevi una risposta in "streaming" (trasmissione in flusso) tramite "server-sent events" (eventi inviati dal server), o SSE, può verificarsi un errore dopo che l'API ha già 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

L'API applica limiti di dimensione delle richieste:

Se superi questi limiti, riceverai un errore 413 request_too_large. Sulla Claude API diretta, 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:

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

In conformità con la politica di versionamento, i valori all'interno di questi oggetti possono espandersi, ed è possibile che i valori di type aumentino nel tempo.

Tipi di errore degli SDK

Per questi errori, gli SDK ufficiali sollevano eccezioni tipizzate invece di restituire JSON grezzo. I nomi delle classi e i namespace variano a seconda del linguaggio. Ad esempio, un 404 si presenta come anthropic.NotFoundError. L'SDK Go usa un unico tipo di errore per tutti gli stati, *anthropic.Error: per distinguere i casi, usa StatusCode. Intercetta le classi tipizzate dell'SDK anziché confrontare le stringhe dei messaggi di errore, e gestisci prima le classi più specifiche. La pagina di ciascun SDK documenta la gerarchia completa delle eccezioni:

• Python · TypeScript · C# · Go · Java · PHP · Ruby

ID della richiesta

Ogni risposta dell'API include un header request-id univoco, con 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 usare la Messages API in streaming o la Message Batches API:

• Alcune reti possono 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 per affidabilità. La Message Batches API 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 costruendo un'integrazione diretta con l'API, impostare un TCP socket keep-alive può ridurre l'impatto dei timeout delle connessioni inattive su alcune reti.

Gli SDK verificano che le tue richieste non in streaming alla Messages API non superino presumibilmente un timeout di 10 minuti. Impostano inoltre un'opzione del socket per il TCP keep-alive.

Se non hai bisogno di elaborare gli eventi in modo incrementale, gli SDK possono 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 Messaggi in streaming 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 dei messaggi dell'assistente. L'invio di una richiesta con un ultimo messaggio dell'assistente precompilato a uno qualsiasi di questi modelli 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, le istruzioni nel "system prompt" (prompt di sistema), oppure output_config.format.

I blocchi di ragionamento non possono essere modificati

Se il messaggio dell'assistente più recente contiene blocchi thinking o redacted_thinking che sono stati modificati, riordinati, filtrati o ricostruiti prima di essere rinviati all'API, la richiesta restituisce 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), ogni blocco thinking e redacted_thinking del turno dell'assistente deve essere restituito esattamente come ricevuto, inclusi i blocchi il cui campo thinking è vuoto. Restituisci i blocchi di ragionamento invariati e, se la tua applicazione filtra i blocchi di contenuto per tipo prima di rinviarli, includi sia thinking sia redacted_thinking. Consulta Risoluzione dei problemi del ragionamento, Preservare i blocchi di ragionamento e Ragionamento preservato.

Ragionamento esteso non supportato

I modelli Claude 4.7 e successivi hanno rimosso 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. Migrazione al ragionamento adattivo mostra la mappatura dei parametri, e Risoluzione dei problemi del ragionamento copre la soluzione a partire dal sintomo.

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 Risoluzione dei problemi del ragionamento per la soluzione a partire dal sintomo.

Il ragionamento non può essere disabilitato

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

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

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

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Con un livello di effort xhigh o max, anche una richiesta con between_tools restituisce un 400 invalid_request_error. Il messaggio 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.

In entrambi i messaggi, "enable thinking" si riferisce al ragionamento adattivo: ometti il campo thinking oppure invia thinking: {"type": "adaptive"}. Claude Sonnet 5.5 rifiuta "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 soluzioni, consulta Risoluzione dei problemi del ragionamento, che tratta gli errori relativi a between_tools e all'effort.

Ometti il parametro thinking: la richiesta verrà 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 Risoluzione dei problemi del ragionamento.

Uso forzato degli strumenti non supportato

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 validi rispetto 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

Sull'API Claude e su Google Cloud, Claude Opus 5.5 e Claude Sonnet 5.5 supportano il computer use solo come toolset computer_toolset_20260801. Su queste piattaforme, l'invio a uno dei due modelli di una voce tools del tipo precedente computer_20251124 (con l'header beta di quello strumento) restituisce un 400 invalid_request_error. Il messaggio indica il tipo rifiutato, quindi elenca i tipi di strumento che il modello accetta dopo Did you mean one of. Per Claude Opus 5.5, inizia così:

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

L'API restituisce lo stesso messaggio per qualsiasi tipo di strumento definito da Anthropic che il modello richiesto non supporta. Dichiara {"type": "computer_toolset_20260801"} senza l'header beta e aggiorna il ciclo del tuo agente come descritto in Migrare da computer_20251124. I modelli precedenti che supportano il toolset continuano ad accettare computer_20251124, come fanno Claude Opus 5.5 e Claude Sonnet 5.5 su Amazon Bedrock.

Il blocco di ragionamento non corrisponde più alla conversazione

Su Claude Fable 5.1, Claude Opus 5.5 e Claude Sonnet 5.5, l'API accetta un blocco di ragionamento riproposto solo finché il prompt system, i tools e i messaggi che lo precedono restano invariati. Per i nuovi account creati a partire dal 31 agosto 2026, e per qualsiasi richiesta che imposti thinking.block_binding.prefix_mismatch_behavior su "error", un blocco riproposto la cui cronologia precedente è cambiata viene rifiutato con un 400 invalid_request_error (con "drop_block", l'API scarta il blocco e la richiesta va a buon fine). Il messaggio inizia con la posizione del primo blocco non valido:

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

Senza l'header beta thinking-binding-controls-2026-08-01, il messaggio indica anche quell'header. Mantieni la cronologia della conversazione in sola aggiunta, oppure invia l'header beta con prefix_mismatch_behavior: "drop_block" per scartare il blocco e continuare. Su Claude Sonnet 5.5, block_binding funziona solo con thinking: {"type": "adaptive"}. Con between_tools, mantieni la cronologia in sola aggiunta, oppure rimuovi i blocchi di ragionamento a partire dal turno modificato. Un blocco proveniente da un modello che il modello di destinazione non è in grado di leggere viene scartato anziché rifiutato. Consulta Mantenere invariato il prefisso e 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, 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 ogni account AWS. Consulta Abilitare la federazione dell'identità web in uscita per i dettagli.

Passaggi successivi