Erreurs HTTP

Notre 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. Nous pouvons également utiliser ce type d’erreur pour d’autres codes de statut 4XX non listés ci-dessous.

  • 401 - authentication_error : Il y a un problème avec votre clé API.

  • 403 - permission_error : Votre clé API n’a pas la permission 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 maximum d’octets autorisé.

  • 429 - rate_limit_error : Votre compte a atteint une limite de taux.

  • 500 - api_error : Une erreur inattendue s’est produite à l’intérieur des systèmes d’Anthropic.

  • 529 - overloaded_error : L’API d’Anthropic est temporairement surchargée.

    Les erreurs 529 peuvent se produire lorsque les API d’Anthropic connaissent un trafic élevé sur tous les utilisateurs. Dans de rares cas, si votre organisation a une augmentation soudaine de l’utilisation, vous pourriez voir ce type d’erreur. Pour éviter les erreurs 529, augmentez votre trafic progressivement et maintenez des modèles d’utilisation cohérents.

Lors de la réception d’une réponse en streaming via SSE, il est possible qu’une erreur puisse se produire après avoir retourné une réponse 200, auquel cas la gestion des erreurs ne suivrait pas ces mécanismes standard.

Formes d’erreurs

Les erreurs sont toujours retournées en JSON, avec un objet error de niveau supérieur qui inclut toujours une valeur type et message. Par exemple :

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

Conformément à notre politique de versioning, nous pouvons étendre les valeurs dans ces objets, et il est possible que les valeurs type augmentent avec le temps.

ID de requête

Chaque réponse API inclut un en-tête unique request-id. Cet en-tête contient une valeur telle que req_018EeWyXxfu5pfWkrYcMdjWG. Lorsque vous contactez le support concernant une requête spécifique, veuillez inclure cet ID pour nous aider à résoudre rapidement votre problème.

Nos SDK officiels fournissent cette valeur comme propriété sur les objets de réponse de niveau supérieur, contenant la valeur de l’en-tête request-id :

import anthropic

client = anthropic.Anthropic()

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

Requêtes longues

Nous encourageons fortement l’utilisation de l’API Messages en streaming ou de l’API Message Batches pour les requêtes de longue durée, en particulier celles de plus de 10 minutes.

Nous ne recommandons pas de définir de grandes valeurs max_tokens sans utiliser notre API Messages en streaming ou notre API Message Batches :

  • Certains réseaux peuvent abandonner les connexions inactives après une période de temps variable, ce qui peut causer l’échec ou le timeout de la requête sans recevoir de réponse d’Anthropic.
  • Les réseaux diffèrent en fiabilité ; notre API Message Batches peut vous aider à gérer le risque de problèmes de réseau en vous permettant de sonder les résultats plutôt que d’exiger une connexion réseau ininterrompue.

Si vous construisez une intégration API directe, vous devriez être conscient que définir un TCP socket keep-alive peut réduire l’impact des timeouts de connexion inactive sur certains réseaux.

Nos SDK valideront que vos requêtes API Messages non-streaming ne sont pas censées dépasser un timeout de 10 minutes et définiront également une option de socket pour TCP keep-alive.