Erreurs



Erreurs HTTP

L'API suit un format de code d'erreur HTTP prévisible :

• 400 - invalid_request_error : Il y a eu un problème avec le format ou le contenu de votre requête. Ce type d'erreur peut également être utilisé pour d'autres codes d'état 4XX non répertoriés dans cette section.

• 401 - authentication_error : Il y a un problème avec votre clé API. Sur Claude Platform sur AWS, cela peut également indiquer un problème avec vos identifiants AWS ou votre signature SigV4.

• 402 - billing_error : Il y a un problème avec vos informations de facturation ou de paiement. Vérifiez vos informations de paiement dans la Claude Console, ou dans AWS Marketplace si vous utilisez Claude Platform sur AWS.

• 403 - permission_error : Votre clé API n'a pas l'autorisation d'utiliser la ressource spécifiée.

• 404 - not_found_error : La ressource demandée n'a pas été trouvée.

• 413 - request_too_large : La requête dépasse le nombre maximal d'octets autorisé. Consultez Limites de taille des requêtes pour connaître les maximums par point de terminaison.

• 429 - rate_limit_error : Votre compte a atteint une limite de débit.

• 500 - api_error : Une erreur inattendue s'est produite dans les systèmes internes d'Anthropic.

• 504 - timeout_error : La requête a expiré pendant le traitement. Envisagez d'utiliser le streaming pour les requêtes de longue durée.

• 529 - overloaded_error : L'API est temporairement surchargée.

  

  Les erreurs 529 peuvent survenir lorsque les API connaissent un trafic élevé pour l'ensemble des utilisateurs.

  Dans de rares cas, si votre organisation connaît une forte augmentation de l'utilisation, vous pourriez voir des erreurs 429 en raison des limites d'accélération sur l'API. Pour éviter d'atteindre les limites d'accélération, augmentez progressivement votre trafic et maintenez des schémas d'utilisation cohérents.

Lors de la réception d'une réponse en streaming via SSE, il est possible qu'une erreur survienne après le renvoi d'une réponse 200, auquel cas la gestion des erreurs ne suivrait pas ces mécanismes standard.



Limites de taille des requêtes

L'API applique des limites de taille de requête pour garantir des performances optimales :

Si vous dépassez ces limites, vous recevrez une erreur 413 request_too_large. Sur l'API Claude directe, cette erreur est renvoyée par Cloudflare avant que la requête n'atteigne les serveurs de l'API.



Structure des erreurs

Les erreurs sont toujours renvoyées au format JSON, avec un objet error de niveau supérieur qui inclut toujours une valeur type et message. La réponse inclut également un champ request_id pour faciliter le suivi et le débogage. Par exemple :

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

Conformément à la politique de gestion des versions, les valeurs au sein de ces objets peuvent être étendues, et il est possible que les valeurs type augmentent au fil du temps.



Types d'erreurs des SDK

Les SDK officiels lèvent des exceptions typées pour ces erreurs au lieu de renvoyer du JSON brut, et les noms de classes et les espaces de noms diffèrent selon le langage. Par exemple, une erreur 404 apparaît sous la forme anthropic.NotFoundError en Python, Anthropic::Errors::NotFoundError en Ruby, com.anthropic.errors.NotFoundException en Java, et sous la forme d'une valeur unique *anthropic.Error (branchement sur StatusCode) en Go. Interceptez les classes typées du SDK plutôt que de faire correspondre des chaînes de caractères aux messages d'erreur, en traitant d'abord les classes les plus spécifiques. Chaque page de SDK documente sa hiérarchie complète d'exceptions :

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



Identifiant de requête

Chaque réponse de l'API inclut un en-tête request-id unique. Cet en-tête contient une valeur telle que req_018EeWyXxfu5pfWkrYcMdjWG. Lorsque vous contactez le support au sujet d'une requête spécifique, incluez cet identifiant pour aider à résoudre rapidement votre problème.

Sur Claude Platform sur AWS, les réponses incluent deux identifiants de requête : l'identifiant de requête AWS (x-amzn-requestid, principal, indexé dans CloudTrail) et l'identifiant de requête Anthropic (request-id, secondaire). Utilisez l'identifiant de requête AWS pour les recherches CloudTrail et l'identifiant de requête Anthropic pour les tickets de support Anthropic.

Les SDK officiels fournissent l'identifiant de requête Anthropic en tant que propriété sur les objets de réponse de niveau supérieur, contenant la valeur de l'en-tête request-id. Sur Claude Platform sur AWS, utilisez l'accesseur de réponse brute pour lire également l'identifiant de requête AWS à partir des en-têtes 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}")

Pour des exemples d'identifiants de requête Claude Platform sur AWS dans d'autres langages, consultez Identifiants de requête.



Requêtes longues

Évitez de définir une valeur max_tokens élevée sans utiliser l'API Messages en streaming ou l'API Message Batches :

• Certains réseaux peuvent interrompre les connexions inactives après une période variable, ce qui peut entraîner l'échec ou l'expiration de la requête sans recevoir de réponse d'Anthropic.
• Les réseaux diffèrent en termes de fiabilité ; l'API Message Batches peut vous aider à gérer le risque de problèmes réseau en vous permettant d'interroger les résultats plutôt que de nécessiter une connexion réseau ininterrompue.

Si vous créez une intégration directe avec l'API, sachez que la configuration d'un keep-alive de socket TCP peut réduire l'impact des délais d'expiration de connexion inactive sur certains réseaux.

Les SDK valident que vos requêtes à l'API Messages sans streaming ne devraient pas dépasser un délai d'expiration de 10 minutes et définissent également une option de socket pour le keep-alive TCP.

Si vous n'avez pas besoin de traiter les événements de manière incrémentielle, utilisez .stream() avec .get_final_message() (Python) ou .finalMessage() (TypeScript) pour obtenir l'objet Message complet sans écrire de code de gestion d'événements :

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)

Consultez Messages en streaming pour plus de détails.



Erreurs de validation courantes



Préremplissage non pris en charge

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 et Claude Sonnet 4.6 ne prennent pas en charge le préremplissage des messages de l'assistant. L'envoi d'une requête avec un dernier message de l'assistant prérempli à l'un de ces modèles renvoie une erreur 400 invalid_request_error :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prefilling assistant messages is not supported for this model."
  }
}

Utilisez plutôt les sorties structurées sur les modèles qui les prennent en charge, des instructions dans l'invite système, ou output_config.format.



Les blocs de réflexion ne peuvent pas être modifiés

Si le message le plus récent de l'assistant contient des blocs thinking ou redacted_thinking qui ont été modifiés, réordonnés, filtrés ou reconstruits avant d'être renvoyés à l'API, la requête renvoie une erreur 400 invalid_request_error. Le message d'erreur commence par la position du bloc problématique (par exemple, messages.1.content.0) et contient :

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

Avec l'utilisation d'outils, chaque bloc thinking et redacted_thinking du tour de l'assistant doit être renvoyé exactement tel qu'il a été reçu, y compris les blocs dont le champ thinking est vide. Renvoyez les blocs de réflexion sans modification, et si votre application filtre les blocs de contenu par type avant de les renvoyer, incluez à la fois thinking et redacted_thinking. Consultez Préservation des blocs de réflexion et Sortie de réflexion sur Claude Fable 5 et Claude Mythos 5.



Fédération d'identité web sortante désactivée (Claude Platform sur AWS)

Si chaque requête vers Claude Platform sur AWS renvoie "Outbound web identity federation is disabled for your account", exécutez aws iam enable-outbound-web-identity-federation une fois par compte AWS. Consultez Activer la fédération d'identité web sortante pour plus de détails.