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 un format 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 contenant un objet error avec les champs 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."
  }
}

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

Le tableau suivant vous indique d'un coup d'œil s'il faut réessayer. Chaque section qui suit présente le corps d'erreur exact 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 reproduit 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 limit ; consultez les contraintes de paramètres sur la page correspondante de la référence de l'API Compliance.

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 projet (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 à aucune 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 coffre 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 Claude Console (clés Admin API), et confirmez qu'elle est activée. Consultez Obtenir l'accès à 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 exact liste les portées que la clé porte (Got:) et les portées que le point de terminaison requiert (Needed:), afin que vous puissiez confirmer ce que la clé porte sans revérifier dans Claude Console ou claude.ai. Les portées des Compliance Access Keys sont immuables après création, donc chaque correction de portée insuffisante vous invite à créer une nouvelle clé plutôt qu'à modifier celle 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 menant à 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 cette portée ; consultez Après l'activation : organisations Claude Console.

Correction : Les portées des Compliance Access Keys sont immuables après 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 connaître 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 ou de groupes. Il existe deux chemins courants menant à 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 portent uniquement 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 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, messages, fichiers, projets, utilisateurs d'organisation ou membres de groupe. Il existe deux chemins courants menant à 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 portent uniquement 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 conversation, fichier, projet, pièce jointe de projet, utilisateur ou membre de groupe.

Correction : Utilisez une Compliance Access Key créée dans claude.ai avec read:compliance_user_data sélectionné. Si la requête doit réellement concerner uniquement l'Activity Feed, dirigez 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, fichiers ou 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 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 passer 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 à aucune conversation lisible via l'API Compliance. La conversation a peut-être été supprimée définitivement via un appel précédent à l'API Compliance ou retirée par la politique de rétention de votre organisation, ou elle appartient peut-être à 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é claude_chat_created ou claude_chat_viewed récente. 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 hors 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 : Effectuez un rapprochement avec les activités claude_file_uploaded ou claude_file_deleted récentes. 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 : Effectuez un rapprochement avec les activités claude_project_created ou claude_project_deleted récentes. 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 texte de projet (claude_proj_doc_...), et non 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 le 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 à aucun 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 effectuez un rapprochement avec les activités récentes d'organisation, de rôle ou de groupe dans l'Activity Feed.

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 point de terminaison de liste de conversations 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 à 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 (Compliance Access Keys et 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 comporte é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 à /v1/compliance/* dans une fenêtre de 1 minute, toutes clés et organisations liées confondues.

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, supprimé par un intermédiaire), revenez à 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é API Claude 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 n'a 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étisez votre taux de requêtes agrégé (toutes clés, organisations liées et workers concurrents confondus) 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 comporte 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 nouvelle tentative 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.

Taille de réponse maximale dépassée

Type : api_error

Response exceeds maximum of 1,000 organizations. Contact support for assistance with larger organization lists.

Cause : Un point de terminaison de liste sans pagination (notamment GET /v1/compliance/organizations) aurait renvoyé plus que son plafond strict de 1 000 enregistrements.

Correction : Le point de terminaison des organisations renvoie l'arborescence complète en un seul appel, jusqu'à 1 000 organisations liées. Si votre arborescence dépasse 1 000, contactez le support Anthropic pour obtenir de l'aide avec des listes d'organisations plus grandes. Si vous interrogiez ce point de terminaison pour suivre les changements d'appartenance aux organisations, le relistage périodique reste l'approche la plus fiable une fois le plafond résolu ; il détecte les ajouts et les suppressions quel que soit le côté de la relation parent-enfant qui les a initiés. L'Activity Feed expose également les événements d'appartenance via les types d'activité org_deletion_requested, org_deleted_via_bulk, org_parent_join_proposal_created et org_join_proposal_decided, que vous pouvez utiliser pour déclencher un relistage immédiat au lieu d'attendre le prochain intervalle d'interrogation.

Étapes suivantes