Errori



Errori HTTP

L'API segue un formato prevedibile di 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 utilizzato anche per altri codici di stato 4XX non elencati in questa sezione.

• 401 - authentication_error: C'è un problema con la tua chiave API. Su Claude Platform on 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 pagamento. Verifica i tuoi dettagli di pagamento nella Claude Console, o in AWS Marketplace se stai utilizzando Claude Platform on AWS.

• 403 - permission_error: La tua chiave API non ha l'autorizzazione per utilizzare la risorsa specificata.

• 404 - not_found_error: La risorsa richiesta non è stata trovata.

• 413 - request_too_large: La richiesta supera il numero massimo consentito di byte. Consulta Limiti di dimensione delle richieste per i valori 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.

• 504 - timeout_error: La richiesta è andata in timeout durante l'elaborazione. Considera l'utilizzo dello streaming per richieste di lunga durata.

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

  

  Gli errori 529 possono verificarsi quando le API registrano un traffico elevato tra tutti gli utenti.

  In rari casi, se la tua organizzazione ha un forte aumento nell'utilizzo, potresti vedere errori 429 a causa dei limiti di accelerazione sull'API. Per evitare di raggiungere i limiti di accelerazione, aumenta gradualmente il tuo traffico e mantieni pattern di utilizzo costanti.

Quando si riceve una risposta in streaming tramite SSE, è possibile che si verifichi un errore dopo aver restituito una risposta 200, nel qual caso la gestione degli errori non seguirebbe questi meccanismi standard.



Limiti di dimensione delle richieste

L'API applica limiti di dimensione delle richieste per garantire prestazioni ottimali:

Se superi questi limiti, riceverai un errore 413 request_too_large. Sull'API Claude diretta, questo errore viene restituito da Cloudflare prima che la richiesta raggiunga i server dell'API.



Struttura degli errori

Gli errori vengono sempre restituiti 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 versioning, i valori all'interno di questi oggetti potrebbero espandersi, ed è possibile che i valori type aumentino 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 a seconda del linguaggio. Ad esempio, un errore 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 fare string-matching sui messaggi di errore, gestendo prima le classi più specifiche. Ogni pagina dell'SDK documenta la propria gerarchia completa delle eccezioni:

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



Request ID

Ogni risposta dell'API include un header request-id univoco. Questo header contiene un valore come req_018EeWyXxfu5pfWkrYcMdjWG. Quando contatti il supporto riguardo a una richiesta specifica, includi questo ID per aiutare a risolvere rapidamente il tuo problema.

Su Claude Platform on AWS, le risposte includono due request ID: l'AWS request ID (x-amzn-requestid, primario, indicizzato in CloudTrail) e l'Anthropic request ID (request-id, secondario). Usa l'AWS request ID per le ricerche in CloudTrail e l'Anthropic request ID per i ticket di supporto Anthropic.

Gli SDK ufficiali forniscono l'Anthropic request ID come proprietà sugli oggetti di risposta di primo livello, contenente il valore dell'header request-id. Su Claude Platform on AWS, usa l'accessor per la risposta grezza per leggere anche l'AWS request ID dagli header HTTP:

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

Per esempi di request ID di Claude Platform on AWS in altri linguaggi, consulta Request ID.



Richieste lunghe

Evita di impostare un valore max_tokens elevato senza utilizzare la Messages API in streaming o la Message Batches API:

• 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 affidabilità; la Message Batches API può aiutarti a gestire il rischio di problemi di rete consentendoti di eseguire il polling dei risultati invece di richiedere una connessione di rete ininterrotta.

Se stai costruendo un'integrazione API diretta, dovresti essere consapevole che 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-streaming alla Messages API non siano previste superare un timeout di 10 minuti e imposteranno anche un'opzione socket per il TCP keep-alive.

Se non hai bisogno di elaborare gli eventi in modo incrementale, usa .stream() con .get_final_message() (Python) o .finalMessage() (TypeScript) per ottenere l'oggetto Message completo senza scrivere codice di gestione degli eventi:

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

Consulta Messaggi in streaming per maggiori dettagli.



Errori di validazione comuni



Prefill non supportato

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6 non supportano il prefilling 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": "Prefilling assistant messages is not supported for this model."
  }
}

Usa invece gli output strutturati sui modelli che li supportano, le istruzioni nel prompt di sistema, o output_config.format.



Outbound web identity federation 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 account AWS. Consulta Abilitare l'outbound web identity federation per i dettagli.