Gérer les erreurs de l'API Compliance

Cette page répertorie les messages de réponse renvoyés par chaque point de terminaison documenté de l'API Compliance, leur cause et leur correction.

L'API Compliance renvoie les erreurs dans le format d'erreur Anthropic standard : un code de statut non-2xx, un en-tête de réponse request-id et un corps JSON avec un objet error contenant type et message. Incluez la valeur de l'en-tête request-id lorsque vous escaladez au support.

{
  "error": {
    "type": "authentication_error",
    "message": "The API key provided is invalid or has been revoked."
  }
}

Faites correspondre sur error.type, pas sur la chaîne du message. Les messages sont suffisamment stables pour être copiés dans des runbooks, mais ils peuvent être reformulés au fil du temps ; les valeurs de type font partie du contrat de l'API.

Le tableau suivant vous indique en un coup d'œil s'il faut réessayer. Chaque section qui suit présente le corps d'erreur textuel et la correction.



400 Bad Request

La requête était syntaxiquement valide mais contenait un paramètre que le serveur a rejeté. Corrigez le paramètre et réessayez.



Format d'horodatage invalide

Type : invalid_request_error

The `created_at.gte` parameter contains an invalid timestamp format. Timestamps must be provided in RFC 3339 format e.g., "2024-03-01T00:00:00Z". Got "2024-01-01".

Cause : Une valeur created_at.* ou updated_at.* (.gte, .gt, .lte, .lt) n'a pas pu être analysée comme une date-heure. Le message nomme le paramètre qui a échoué et reprend la valeur qui a été envoyée.

Correction : Envoyez un horodatage RFC 3339 complet incluant l'heure et le fuseau horaire, par exemple 2024-03-01T00:00:00Z ou 2024-03-01T00:00:00+00:00.



Limite invalide

Type : invalid_request_error

The limit parameter must be between 1 and 1000, inclusive. Got 1500.

Cause : Le paramètre de requête limit était en dehors de la plage acceptée. La borne nommée dans le message reflète le maximum pour le point de terminaison spécifique qui a été appelé.

Correction : Envoyez une valeur limit dans la plage acceptée par le point de terminaison. Chaque point de terminaison de liste a sa propre plage de limit ; consultez les contraintes de paramètres sur la page de référence de l'API Compliance correspondante.



ID de pagination invalide

Type : invalid_request_error

Invalid `after_id`. No activity found for `after_id` "activity_invalid123"

Cause : Le curseur after_id ou before_id n'a pas pu être décodé comme un curseur opaque ni analysé comme un ID d'activité.

Correction : Traitez les curseurs de pagination comme des chaînes opaques. Copiez toujours la valeur first_id ou last_id renvoyée par la page précédente ; arrêtez-vous lorsque has_more est false. Ne construisez pas de curseurs à partir d'ID d'objets.

Les points de terminaison d'annuaire et de projets (organisations, utilisateurs, rôles, permissions de rôles, groupes, membres de groupes, projets et pièces jointes de projets) paginent avec un jeton page opaque plutôt qu'avec after_id et before_id. Le même conseil s'applique : transmettez la valeur next_page de la réponse précédente sans la modifier, et arrêtez-vous lorsque has_more est false. Un jeton page mal formé renvoie la même erreur 400 invalid_request_error qu'un after_id ou before_id mal formé.



401 Unauthorized

L'en-tête x-api-key était manquant ou ne correspondait pas à une clé connue. Une clé valide avec les mauvaises portées renvoie plutôt 403 Forbidden.



Clé API invalide

Type : authentication_error

The API key provided is invalid or has been revoked.

Cause : La clé dans x-api-key n'existe pas, a été supprimée ou a été désactivée. Un en-tête x-api-key manquant ou vide renvoie le même corps, vérifiez donc à la fois votre magasin de secrets et le statut de révocation de la clé.

Correction : Confirmez la valeur de la clé, vérifiez qu'elle n'a pas été supprimée dans claude.ai (Compliance Access Keys) ou dans Claude Console (clés Admin API), et confirmez qu'elle est activée. Consultez Configurer l'API Compliance.



403 Forbidden

La clé dans x-api-key est valide mais ne porte pas la portée requise par le point de terminaison. Le message textuel liste les portées que la clé porte (Got:) et les portées requises par le point de terminaison (Needed:), afin que vous puissiez confirmer ce que la clé porte sans revérifier Claude Console ou claude.ai. Les portées d'une Compliance Access Key sont immuables après sa création, donc chaque correction de portée insuffisante vous oriente vers la création d'une nouvelle clé plutôt que vers la modification de la clé existante.



Portée insuffisante : Activity Feed

Type : permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['read:compliance_activities']

Cause : Une clé sans read:compliance_activities a été utilisée pour appeler GET /v1/compliance/activities. Il existe deux chemins courants vers cette erreur :

• Une Compliance Access Key (sk-ant-api01-...) a été créée sans la portée read:compliance_activities.
• Une clé Admin API de Claude Console (sk-ant-admin01-...) a été créée avant que l'API Compliance ne soit activée pour l'organisation. Les clés créées avant l'activation ne portent pas la portée ; consultez Configurer l'API Compliance.

Correction : Les portées d'une Compliance Access Key sont immuables après sa création. Créez une nouvelle clé qui inclut read:compliance_activities, ou utilisez une clé Admin API de Claude Console. Consultez De quelle clé avez-vous besoin ? pour les conditions dans lesquelles une clé Admin API porte cette portée.



Portée insuffisante : données d'organisation

Type : permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['read:compliance_org_data']

Cause : Une clé sans read:compliance_org_data a été utilisée pour appeler un point de terminaison d'organisations, de rôles, de groupes ou de paramètres effectifs. Il existe deux chemins courants vers cette erreur :

• Une Compliance Access Key (sk-ant-api01-...) a été créée sans la portée read:compliance_org_data.
• Une clé Admin API de Claude Console (sk-ant-admin01-...) a été utilisée. Les clés Admin API ne portent que read:compliance_activities et ne peuvent pas lire les métadonnées d'organisation.

Correction : Créez une nouvelle Compliance Access Key avec read:compliance_org_data sélectionné. Les clés Admin API ne peuvent pas lire les métadonnées d'organisation ; la Compliance Access Key est requise.



Portée retirée : paramètres d'organisation

Type : permission_error

Missing required scopes. Got: ['read:compliance_org_settings'] Needed: ['read:compliance_org_data']

Cause : La portée read:compliance_org_settings a été retirée le 30 juin 2026. GET /v1/compliance/organizations/{organization_id}/settings requiert désormais read:compliance_org_data, la même portée que les autres points de terminaison d'organisation, et la portée retirée n'autorise plus rien. Une Compliance Access Key qui ne porte que read:compliance_org_settings renvoie cette erreur à chaque appel au point de terminaison des paramètres, même si la clé fonctionnait avant le retrait. La portée retirée ne peut plus être sélectionnée ni accordée lors de la création d'une clé.

Correction : Les portées d'une Compliance Access Key sont immuables après sa création. Créez une nouvelle Compliance Access Key avec read:compliance_org_data sélectionné, mettez à jour votre intégration pour l'utiliser, puis supprimez l'ancienne clé. Une clé qui porte déjà read:compliance_org_data n'est pas affectée par le retrait.



Portée insuffisante : données utilisateur

Type : permission_error

Missing required scopes. Got: ['read:compliance_activities'] Needed: ['read:compliance_user_data']

Cause : Une clé sans read:compliance_user_data a été utilisée pour appeler un point de terminaison de conversations, de messages, de fichiers, de projets, d'utilisateurs de l'organisation, ou de membres de groupes. Il existe deux chemins courants vers cette erreur :

• Une Compliance Access Key (sk-ant-api01-...) a été créée sans la portée read:compliance_user_data.
• Une clé Admin API de Claude Console (sk-ant-admin01-...) a été utilisée. Les clés Admin API ne portent que read:compliance_activities et ne peuvent pas se voir accorder read:compliance_user_data, elles ne peuvent donc pas appeler les points de terminaison de conversations, de fichiers, de projets, de pièces jointes de projets, d'utilisateurs, ou de membres de groupes.

Correction : Utilisez une Compliance Access Key créée dans claude.ai avec read:compliance_user_data sélectionné. Si la requête doit vraiment se limiter à l'Activity Feed, pointez plutôt la clé Admin API vers GET /v1/compliance/activities.



Portée insuffisante : suppression

Type : permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['delete:compliance_user_data']

Cause : Une Compliance Access Key sans delete:compliance_user_data a été utilisée pour appeler un point de terminaison DELETE sur des conversations, des fichiers ou des projets.

Correction : Créez une nouvelle Compliance Access Key avec delete:compliance_user_data sélectionné. La portée de suppression est distincte de read:compliance_user_data afin que les clés d'audit en lecture seule ne puissent pas supprimer de contenu.



404 Not Found

Le point de terminaison a été résolu mais l'ID de la ressource n'existe pas ou a déjà été supprimé. Les suppressions de l'API Compliance sont immédiates et permanentes, donc un 404 sur un ID précédemment connu signifie généralement que le contenu a été supprimé définitivement via un appel de suppression de l'API Compliance ou retiré par une politique de rétention. Les chaînes de type d'activité citées dans chaque correction (par exemple, claude_chat_created) sont des valeurs que vous pouvez transmettre au filtre activity_types[] de l'Activity Feed ; consultez Interroger les activités de conformité pour toutes les valeurs prises en charge.



Conversation introuvable

Type : not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

Cause : L'ID de conversation dans le chemin ne correspond pas à une conversation lisible via l'API Compliance. La conversation peut avoir été supprimée définitivement via un appel précédent de l'API Compliance ou retirée par la politique de rétention de votre organisation, ou elle peut appartenir à une organisation que la clé appelante ne peut pas lire. Les conversations qu'un utilisateur a supprimées de manière réversible dans claude.ai ne renvoient pas 404 ; elles restent lisibles avec deleted_at renseigné.

Correction : Confirmez l'ID de conversation par rapport à une activité récente claude_chat_created ou claude_chat_viewed. Si l'activité est récente et que la lecture échoue toujours, la conversation a été supprimée définitivement (via cette API ou par expiration de la politique de rétention) ou appartient à une organisation en dehors de la portée de votre clé.



Fichier introuvable

Type : not_found_error

No file found with provided id, or it has already been deleted.

Cause : L'ID de fichier n'existe pas ou a été supprimé. Cette erreur s'applique à la fois aux fichiers joints aux conversations (claude_file_...) et aux fichiers de projet.

Correction : Rapprochez avec les activités récentes claude_file_uploaded ou claude_file_deleted. Si le fichier a été supprimé, le binaire a disparu ; l'enregistrement d'activité reste dans le flux pendant la fenêtre de rétention de 6 ans.



Projet introuvable

Type : not_found_error

No project is found with the provided id.

Cause : L'ID de projet n'existe pas ou a été supprimé.

Correction : Rapprochez avec les activités récentes claude_project_created ou claude_project_deleted. L'Activity Feed continue d'exposer les événements du cycle de vie du projet même après la disparition du projet lui-même.



Document de projet introuvable

Type : not_found_error

No project document found with provided id, or it has already been deleted.

Cause : L'ID du document de projet n'existe pas ou a été supprimé. Cette erreur s'applique aux documents de projet textuels (claude_proj_doc_...), pas aux fichiers de projet.

Correction : Utilisez GET /v1/compliance/apps/projects/{project_id}/attachments pour lister les pièces jointes actuelles. Si le document est manquant, il a été supprimé ; récupérez-le via un enregistrement d'activité claude_project_document_uploaded si vous n'avez besoin que des métadonnées.



Organisation, rôle ou groupe introuvable

Type : not_found_error

The "ce86b5f3-7c16-48b3-a9f3-e1d2c4b8a0f1" organization does not exist or the requester is not authorized to access it.

Les points de terminaison d'organisation, de rôle et de groupe renvoient une erreur 404 not_found_error dans le format d'erreur standard. Le message d'organisation nomme l'org_uuid ; les messages de rôle et de groupe sont génériques (Role not found., Group not found.). Cela se produit lorsqu'un ID de chemin (org_uuid, role_id ou group_id) n'existe pas ou n'appartient plus à une arborescence que la clé appelante peut lire.

Cause : L'ID dans le chemin ne correspond pas à un enregistrement lisible via l'API Compliance. Les rôles et les groupes peuvent être supprimés, et les organisations peuvent être dissociées de l'arborescence parente.

Correction : Vérifiez l'ID par rapport au point de terminaison de liste correspondant, et rapprochez avec les activités récentes d'organisation, de rôle ou de groupe dans l'Activity Feed.



Paramètres d'organisation non disponibles

Type : not_found_error

organization `91012d09-e48b-438e-a489-1bebfd8fa6f9` not found in this organization's hierarchy

Cause : GET /v1/compliance/organizations/{organization_id}/settings renvoie ce 404 dans trois cas qui partagent intentionnellement le même corps afin que la réponse ne révèle pas si une organisation existe : l'organization_id ne fait pas partie des organisations liées de votre parent, la valeur n'est pas un UUID valide, ou le point de terminaison des paramètres n'est pas encore activé pour votre organisation parente.

Correction : Vérifiez l'ID par rapport à Lister les organisations. Si un ID d'organisation connu comme valide renvoie toujours 404, le point de terminaison des paramètres n'est pas encore activé pour votre organisation parente ; contactez votre représentant Anthropic.



409 Conflict

La requête est bien formée et autorisée mais entre en conflit avec l'état actuel de la ressource.



Le projet a des conversations attachées

Type : conflict_error

The "claude_proj_01KGp4eZNug9ri4kE35RSppq" project cannot be deleted as it has chats attached to it. Delete or detach all chats, and try deleting the project again.

Cause : DELETE /v1/compliance/apps/projects/{project_id} a été appelé sur un projet qui a encore des conversations attachées.

Correction : Listez les conversations du projet avec GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} (le filtre project_ids[] requiert au moins une valeur user_ids[] ; énumérez les ID via Lister les utilisateurs de l'organisation), supprimez chacune d'elles avec DELETE /v1/compliance/apps/chats/{claude_chat_id}, puis réessayez la suppression du projet.



429 Too Many Requests

Les requêtes vers l'API Compliance sont limitées à 600 requêtes par minute par organisation parente. La limite est un budget unique partagé entre toutes les clés sous le parent (les Compliance Access Keys et les clés Admin API de toutes les organisations liées) et entre tous les points de terminaison /v1/compliance/*. Contactez votre représentant Anthropic si votre intégration nécessite une limite plus élevée.

Une fois votre clé API authentifiée, chaque réponse de l'API Compliance inclut les en-têtes de réponse de limite de débit standard afin que votre client puisse ralentir de manière proactive au lieu d'attendre un 429 :

• anthropic-ratelimit-requests-limit est le budget de requêtes par minute de votre organisation parente.
• anthropic-ratelimit-requests-remaining est le budget restant dans la fenêtre actuelle.
• anthropic-ratelimit-requests-reset est l'horodatage RFC 3339 auquel la fenêtre se réinitialise et le budget complet est restauré.

Une réponse 429 porte également un en-tête retry-after avec le nombre de secondes à attendre avant d'envoyer la requête suivante. Cette valeur peut inclure une petite marge de sécurité au-delà de anthropic-ratelimit-requests-reset ; respectez retry-after.

HTTP/1.1 429 Too Many Requests
date: Tue, 21 Apr 2026 14:38:02 GMT
retry-after: 25
anthropic-ratelimit-requests-limit: 600
anthropic-ratelimit-requests-remaining: 0
anthropic-ratelimit-requests-reset: 2026-04-21T14:38:25Z

{
  "error": {
    "type": "rate_limit_error",
    "message": "Compliance API rate limit of 600 requests per minute per parent organization has been exceeded. Retry after the time indicated by the retry-after header. Quote the request-id response header when contacting Anthropic support."
  }
}

Cause : Votre organisation parente a envoyé plus de 600 requêtes vers /v1/compliance/* dans une fenêtre de 1 minute, à travers toutes ses clés et organisations liées.

Correction : Attendez le nombre de secondes indiqué dans l'en-tête retry-after, puis réessayez. Si l'en-tête est absent (par exemple, retiré par un intermédiaire), repliez-vous sur un backoff exponentiel (commencez à 1 seconde, doublez jusqu'à 60 secondes). N'avancez pas votre curseur de pagination sur un 429 : la requête échouée n'a renvoyé aucune donnée, donc le curseur de la dernière page réussie est toujours correct.

Les requêtes qui échouent à l'authentification (une clé manquante ou non reconnue, ou une clé Claude API plutôt qu'une Compliance Access Key ou une clé Admin API) sont rejetées avant le limiteur de débit et ne consomment pas de quota. Une clé valide qui ne possède pas la portée requise par le point de terminaison consomme une unité de quota avant que le 403 ne soit renvoyé.

Si vous interrogez l'Activity Feed selon un calendrier, budgétez votre taux de requêtes agrégé (à travers toutes les clés, organisations liées et workers concurrents) en dessous de la limite de l'organisation parente. Surveillez anthropic-ratelimit-requests-remaining pour ralentir avant de l'atteindre. Consultez Concevoir votre intégration de conformité pour choisir entre l'interrogation par fenêtre et l'ingestion pilotée par curseur.



500 Internal Server Error

Un 500 de l'API Compliance porte un en-tête de réponse x-should-retry: false lorsque l'échec est déterministe. Les SDK Anthropic respectent cet en-tête automatiquement. Si vous utilisez une bibliothèque de nouvelles tentatives HTTP générique qui réessaie sur chaque 5xx, supprimez les nouvelles tentatives lorsque x-should-retry est false ; réessayer cette erreur échoue de manière identique à chaque tentative.

Un 500 sans l'en-tête x-should-retry: false est transitoire : réessayez avec un backoff exponentiel (commencez à 1 seconde, doublez jusqu'à 60 secondes). Il en va de même pour les réponses 502, 503, 504 et 529. Consultez Erreurs pour la sémantique de nouvelle tentative à l'échelle de la plateforme.

Pour les incidents à l'échelle du service, consultez status.anthropic.com.



Prochaines étapes