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 solution.

L'API Compliance renvoie les erreurs dans un format d'erreur cohérent avec le reste du format d'erreur Anthropic : 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 faites remonter le problème au support.

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

Effectuez la correspondance 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 solution.



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.

Solution : 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é.

Solution : Envoyez un 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é.

Solution : 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 projet (organisations, utilisateurs, rôles, permissions de rôle, groupes, membres de groupe, projets et pièces jointes de projet) 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 mauvais scopes 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 coffre de secrets et le statut de révocation de la clé.

Solution : 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 le scope requis par le point de terminaison. Le message textuel liste les scopes que la clé porte (Got:) et les scopes requis par le point de terminaison (Needed:), afin que vous puissiez confirmer ce que la clé porte sans revérifier dans Claude Console ou claude.ai. Les scopes d'une Compliance Access Key sont immuables après sa création, donc chaque solution pour un scope insuffisant vous oriente vers la création d'une nouvelle clé plutôt que vers la modification de la clé existante.



Scope insuffisant : 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 menant à cette erreur :

• Une Compliance Access Key (sk-ant-api01-...) a été créée sans le scope 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 le scope ; consultez Configurer l'API Compliance.

Solution : Les scopes 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 Quelle clé vous faut-il ? pour connaître les conditions dans lesquelles une clé Admin API porte ce scope.



Scope insuffisant : 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 menant à cette erreur :

• Une Compliance Access Key (sk-ant-api01-...) a été créée sans le scope 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.

Solution : 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.



Scope retiré : paramètres d'organisation

Type : permission_error

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

Cause : Le scope read:compliance_org_settings a été retiré le 30 juin 2026. GET /v1/compliance/organizations/{organization_id}/settings requiert désormais read:compliance_org_data, le même scope que les autres points de terminaison d'organisation, et le scope retiré 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. Le scope retiré ne peut plus être sélectionné ni accordé lors de la création d'une clé.

Solution : Les scopes 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.



Scope insuffisant : 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 chats, de messages, de fichiers, de projets, d'utilisateurs d'organisation ou de membres de groupe. Il existe deux chemins courants menant à cette erreur :

• Une Compliance Access Key (sk-ant-api01-...) a été créée sans le scope 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 chat, de fichier, de projet, de pièce jointe de projet, d'utilisateur ou de membre de groupe.

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



Scope insuffisant : 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 chats, des fichiers ou des projets.

Solution : Créez une nouvelle Compliance Access Key avec delete:compliance_user_data sélectionné. Le scope de suppression est distinct 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 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 Solution (par exemple, claude_chat_created) sont des valeurs que vous pouvez passer au filtre activity_types[] de l'Activity Feed ; consultez Interroger les activités de conformité pour toutes les valeurs prises en charge.



Chat introuvable

Type : not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

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

Solution : Confirmez l'ID de chat 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, le chat a été supprimé définitivement (via cette API ou par expiration de la politique de rétention) ou appartient à une organisation en dehors du périmètre 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 chats (claude_file_...) et aux fichiers de projet.

Solution : Effectuez un rapprochement 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é.

Solution : Effectuez un rapprochement 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 de 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.

Solution : 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.

Solution : Vérifiez l'ID par rapport au point de terminaison de liste correspondant, et effectuez un rapprochement 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.

Solution : 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 chats attachés

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 chats attachés.

Solution : Listez les chats 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 chacun d'eux 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 se réguler 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 d'une minute, toutes clés et organisations liées confondues.

Solution : 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, supprimé par un intermédiaire), repliez-vous sur un backoff exponentiel (commencez à 1 seconde, doublez jusqu'à 60 secondes). Ne faites pas avancer 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 à laquelle il manque le scope requis 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é (sur l'ensemble des clés, des organisations liées et des 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