Errori dell'API di Claude



Errori HTTP

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

• 400 - invalid_request_error: C'è stato un problema con il formato o il contenuto della tua richiesta. Questo tipo di errore può essere utilizzato anche per altri codici di stato 4XX non elencati in questa sezione.

• 401 - authentication_error: C'è un problema con la tua chiave API (ad esempio, è malformata, revocata o scaduta; consulta Scadenza delle chiavi). Su Claude Platform su AWS, questo 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 tuoi dettagli di pagamento nella Claude Console, o in AWS Marketplace se stai usando Claude Platform su AWS.

• 403 - permission_error: La tua chiave API non ha il permesso di 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 ed 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 in modo concorrente, 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 massimi per endpoint.

• 429 - rate_limit_error: Il tuo account ha raggiunto un limite di velocità.

• 500 - api_error: Si è verificato un errore imprevisto interno ai sistemi di Anthropic. Riprova la richiesta con backoff esponenziale; se l'errore persiste, contatta il supporto con l'ID di richiesta.

• 504 - timeout_error: La richiesta è andata in timeout durante l'elaborazione. Considera l'uso dell'API Messages in streaming per le richieste di lunga durata. Consulta Richieste lunghe per ulteriori opzioni.

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

Gli SDK ufficiali ritentano automaticamente i fallimenti 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. Ogni client SDK accetta un'opzione per il numero massimo di tentativi per configurare o disabilitare questo comportamento.

Quando si riceve una risposta in streaming tramite server-sent events (SSE), un errore può verificarsi dopo che l'API ha restituito una risposta 200. In quel caso, la gestione degli errori non segue questi meccanismi standard. Consulta Eventi di errore per la struttura degli errori a metà 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. Sull'API di Claude 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 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 crescano nel tempo.



Tipi di errore degli SDK

Gli SDK ufficiali sollevano eccezioni tipizzate per questi errori invece di restituire JSON grezzo, e i nomi delle classi e i namespace differiscono per linguaggio. Ad esempio, un 404 si presenta come anthropic.NotFoundError in Python, Anthropic::Errors::NotFoundError in Ruby, com.anthropic.errors.NotFoundException in Java, e come un singolo valore *anthropic.Error (con diramazione su StatusCode) in Go. Intercetta le classi tipizzate dell'SDK invece di confrontare stringhe dei messaggi di errore, gestendo prima le classi più specifiche. Ogni pagina dell'SDK documenta la sua gerarchia completa di eccezioni:

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



ID di richiesta

Ogni risposta dell'API include un header request-id univoco. Questo header contiene un valore come req_018EeWyXxfu5pfWkrYcMdjWG. Lo stesso identificatore appare 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 tuo problema.

Su Claude Platform su 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 di richiesta come proprietà _request_id sugli oggetti di risposta di primo livello. Gli SDK C#, Go, Java e PHP lo espongono tramite i loro accessori di risposta grezza, che ti permettono anche di leggere qualsiasi altro header di risposta. Su Claude Platform su AWS, usa l'accessore di risposta grezza per leggere anche 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 su Claude Platform su AWS in altri linguaggi, consulta ID di richiesta.



Richieste lunghe

Evita di impostare un valore max_tokens elevato senza usare l'API Messages in streaming o l'API Message Batches:

• 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 in affidabilità. L'API Message Batches può aiutarti a gestire il rischio di problemi di rete permettendoti di effettuare il polling dei risultati invece di richiedere una connessione di rete ininterrotta.

Se stai costruendo un'integrazione API diretta, 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 all'API Messages non siano previste superare un timeout di 10 minuti. Impostano anche un'opzione 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 Streaming dei messaggi 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 errore 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 prompt di sistema, oppure output_config.format.



I blocchi di thinking 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 errore 400 invalid_request_error. Il messaggio di errore inizia con la posizione del blocco problematico (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 l'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 thinking senza modifiche e, se la tua applicazione filtra i blocchi di contenuto per tipo prima di rinviarli, includi sia thinking che redacted_thinking. Consulta Risoluzione dei problemi del thinking, Preservare i blocchi di thinking e Output del thinking su Claude Fable 5 e Claude Mythos 5.



Pensiero esteso non supportato

I modelli Claude 4.7 e successivi hanno rimosso il pensiero esteso. L'invio di thinking: {"type": "enabled"} a uno qualsiasi di questi modelli restituisce un errore 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 pensiero adattivo. Migrazione al pensiero adattivo mostra la mappatura dei parametri, e Risoluzione dei problemi del thinking copre la soluzione a partire dal sintomo.



Pensiero adattivo non supportato

I modelli che supportano solo il pensiero esteso (Claude 4.5 e modelli precedenti) rifiutano thinking: {"type": "adaptive"} con un errore 400 invalid_request_error:

adaptive thinking is not supported on this model

Usa thinking: {"type": "enabled", "budget_tokens": N} su questi modelli; consulta Pensiero esteso per la configurazione e Risoluzione dei problemi del thinking per la soluzione a partire dal sintomo.



Il thinking non può essere disabilitato

Su Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, il thinking è sempre attivo. L'invio di thinking: {"type": "disabled"} a uno qualsiasi di questi modelli restituisce un errore 400 invalid_request_error:

"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 Fable 5 e Claude Mythos 5, anche il suggerimento "thinking.type.enabled" contenuto nel messaggio di errore stesso viene rifiutato. Ometti il parametro thinking e la richiesta verrà eseguita con il pensiero adattivo. Per mantenere il contenuto del thinking fuori dalle risposte senza disattivare il thinking, imposta display: "omitted" nella configurazione del thinking. Consulta Risoluzione dei problemi del thinking.



Federazione delle identità web in uscita disabilitata (Claude Platform su AWS)

Se ogni richiesta a Claude Platform su AWS restituisce "Outbound web identity federation is disabled for your account", esegui aws iam enable-outbound-web-identity-federation una volta per account AWS. Consulta Abilitare la federazione delle identità web in uscita per i dettagli.



Prossimi passi