Compliance API-Fehler behandeln

Diese Seite listet die Antwortnachrichten auf, die jeder dokumentierte Compliance API-Endpunkt zurückgibt, sowie die Ursache und die Lösung.

Die Compliance API gibt Fehler in einem Fehlerformat zurück, das mit dem restlichen Anthropic-Fehlerformat konsistent ist: ein Nicht-2xx-Statuscode, ein request-id-Response-Header und ein JSON-Body mit einem error-Objekt, das type und message enthält. Gib den Wert des request-id-Headers an, wenn du an den Support eskalierst.

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

Prüfe auf error.type, nicht auf den Message-String. Die Messages sind stabil genug, um sie in Runbooks zu kopieren, könnten aber im Laufe der Zeit umformuliert werden; die Type-Werte sind Teil des API-Vertrags.

Die folgende Tabelle zeigt dir auf einen Blick, ob du einen Retry durchführen solltest. Jeder nachfolgende Abschnitt zeigt den wortgetreuen Error-Body und die Lösung.

400 Bad Request

Die Anfrage war syntaktisch gültig, enthielt aber einen Parameter, den der Server abgelehnt hat. Korrigiere den Parameter und versuche es erneut.

Ungültiges Zeitstempelformat

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

Ursache: Ein created_at.*- oder updated_at.*-Wert (.gte, .gt, .lte, .lt) konnte nicht als Datetime geparst werden. Die Message nennt den fehlgeschlagenen Parameter und gibt den gesendeten Wert wieder.

Lösung: Sende einen vollständigen RFC 3339-Zeitstempel einschließlich Uhrzeit und Zeitzone, zum Beispiel 2024-03-01T00:00:00Z oder 2024-03-01T00:00:00+00:00.

Ungültiges Limit

Type: invalid_request_error

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

Ursache: Der limit-Query-Parameter lag außerhalb des akzeptierten Bereichs. Die in der Message genannte Grenze spiegelt das Maximum für den spezifischen aufgerufenen Endpunkt wider.

Lösung: Sende ein limit innerhalb des Bereichs, den der Endpunkt akzeptiert. Jeder List-Endpunkt hat seinen eigenen limit-Bereich; siehe die Parameter-Einschränkungen auf der entsprechenden Compliance API-Referenzseite.

Ungültige Paginierungs-ID

Type: invalid_request_error

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

Ursache: Der after_id- oder before_id-Cursor konnte nicht als opaker Cursor dekodiert oder als Activity-ID geparst werden.

Lösung: Behandle Paginierungs-Cursor als opake Strings. Kopiere immer den first_id- oder last_id-Wert, der von der vorherigen Seite zurückgegeben wurde; stoppe, wenn has_more false ist. Konstruiere keine Cursor aus Objekt-IDs.

Die Verzeichnis- und Projekt-Endpunkte (Benutzer, Rollen, Rollenberechtigungen, Gruppen, Gruppenmitglieder, Projekte und Projektanhänge) paginieren mit einem opaken page-Token anstelle von after_id und before_id. Derselbe Rat gilt: Übergib den next_page-Wert aus der vorherigen Antwort unverändert und stoppe, wenn has_more false ist. Ein fehlerhaftes page-Token gibt denselben 400 invalid_request_error zurück wie ein fehlerhaftes after_id oder before_id.

401 Unauthorized

Der x-api-key-Header fehlte oder stimmte mit keinem bekannten Key überein. Ein gültiger Key mit den falschen Scopes gibt stattdessen 403 Forbidden zurück.

Ungültiger API-Key

Type: authentication_error

The API key provided is invalid or has been revoked.

Ursache: Der Key in x-api-key existiert nicht, wurde gelöscht oder wurde deaktiviert. Ein fehlender oder leerer x-api-key-Header gibt denselben Body zurück, prüfe also sowohl deinen Secret-Store als auch den Widerrufsstatus des Keys.

Lösung: Bestätige den Key-Wert, prüfe, dass er nicht in claude.ai (Compliance Access Keys) oder Claude Console (Admin API-Keys) gelöscht wurde, und bestätige, dass er aktiviert ist. Siehe Zugriff auf die Compliance API erhalten.

403 Forbidden

Der Key in x-api-key ist gültig, trägt aber nicht den Scope, den der Endpunkt erfordert. Die wortgetreue Message listet die Scopes auf, die der Key trägt (Got:), und die Scopes, die der Endpunkt erfordert (Needed:), sodass du bestätigen kannst, was der Key trägt, ohne Claude Console oder claude.ai erneut zu prüfen. Compliance Access Key-Scopes sind nach der Erstellung unveränderlich, daher weist dich jede Lösung für unzureichende Scopes an, einen neuen Key zu erstellen, anstatt den bestehenden zu bearbeiten.

Unzureichender Scope: Activity Feed

Type: permission_error

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

Ursache: Ein Key ohne read:compliance_activities wurde verwendet, um GET /v1/compliance/activities aufzurufen. Es gibt zwei häufige Wege zu diesem Fehler:

• Ein Compliance Access Key (sk-ant-api01-...) wurde ohne den read:compliance_activities-Scope erstellt.
• Ein Claude Console Admin API-Key (sk-ant-admin01-...) wurde erstellt, bevor die Compliance API für die Organisation aktiviert wurde. Keys, die vor der Aktivierung erstellt wurden, tragen den Scope nicht; siehe Nach der Aktivierung: Claude Console-Organisationen.

Lösung: Compliance Access Key-Scopes sind nach der Erstellung unveränderlich. Erstelle einen neuen Key, der read:compliance_activities enthält, oder verwende einen Claude Console Admin API-Key. Siehe Welchen Key brauchst du? für die Bedingungen, unter denen ein Admin API-Key diesen Scope trägt.

Unzureichender Scope: Organisationsdaten

Type: permission_error

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

Ursache: Ein Key ohne read:compliance_org_data wurde verwendet, um einen Organisations-, Rollen- oder Gruppen-Endpunkt aufzurufen. Es gibt zwei häufige Wege zu diesem Fehler:

• Ein Compliance Access Key (sk-ant-api01-...) wurde ohne den read:compliance_org_data-Scope erstellt.
• Ein Claude Console Admin API-Key (sk-ant-admin01-...) wurde verwendet. Admin API-Keys tragen nur read:compliance_activities und können keine Organisationsmetadaten lesen.

Lösung: Erstelle einen neuen Compliance Access Key mit ausgewähltem read:compliance_org_data. Admin API-Keys können keine Organisationsmetadaten lesen; der Compliance Access Key ist erforderlich.

Unzureichender Scope: Benutzerdaten

Type: permission_error

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

Ursache: Ein Key ohne read:compliance_user_data wurde verwendet, um einen Chats-, Messages-, Files-, Projects-, Organisationsbenutzer- oder Gruppenmitglieder-Endpunkt aufzurufen. Es gibt zwei häufige Wege zu diesem Fehler:

• Ein Compliance Access Key (sk-ant-api01-...) wurde ohne den read:compliance_user_data-Scope erstellt.
• Ein Claude Console Admin API-Key (sk-ant-admin01-...) wurde verwendet. Admin API-Keys tragen nur read:compliance_activities und können nicht mit read:compliance_user_data ausgestattet werden, daher können sie die Chat-, File-, Project-, Projektanhang-, Benutzer- oder Gruppenmitglieder-Endpunkte nicht aufrufen.

Lösung: Verwende einen Compliance Access Key, der in claude.ai mit ausgewähltem read:compliance_user_data erstellt wurde. Wenn die Anfrage wirklich nur für den Activity Feed gedacht sein sollte, richte den Admin API-Key stattdessen auf GET /v1/compliance/activities.

Unzureichender Scope: Löschen

Type: permission_error

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

Ursache: Ein Compliance Access Key ohne delete:compliance_user_data wurde verwendet, um einen DELETE-Endpunkt für Chats, Files oder Projects aufzurufen.

Lösung: Erstelle einen neuen Compliance Access Key mit ausgewähltem delete:compliance_user_data. Der Delete-Scope ist getrennt von read:compliance_user_data, damit schreibgeschützte Audit-Keys keine Inhalte löschen können.

404 Not Found

Der Endpunkt wurde aufgelöst, aber die Ressourcen-ID existiert nicht oder wurde bereits gelöscht. Compliance API-Löschungen sind sofortig und dauerhaft, daher bedeutet ein 404 bei einer zuvor bekannten ID normalerweise, dass der Inhalt durch einen Compliance API-Delete-Aufruf hart gelöscht oder durch eine Aufbewahrungsrichtlinie entfernt wurde. Die in jeder Lösung zitierten Activity-Type-Strings (zum Beispiel claude_chat_created) sind Werte, die du an den activity_types[]-Filter des Activity Feeds übergeben kannst; siehe Compliance-Aktivitäten abfragen für jeden unterstützten Wert.

Chat nicht gefunden

Type: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

Ursache: Die Chat-ID im Pfad stimmt mit keinem Chat überein, der über die Compliance API lesbar ist. Der Chat wurde möglicherweise durch einen vorherigen Compliance API-Aufruf hart gelöscht oder durch die Aufbewahrungsrichtlinie deiner Organisation entfernt, oder er gehört zu einer Organisation, die der aufrufende Key nicht lesen kann. Chats, die ein Benutzer in claude.ai soft-gelöscht hat, geben kein 404 zurück; sie bleiben lesbar mit gefülltem deleted_at.

Lösung: Bestätige die Chat-ID anhand einer aktuellen claude_chat_created- oder claude_chat_viewed-Aktivität. Wenn die Aktivität aktuell ist und das Lesen trotzdem fehlschlägt, wurde der Chat hart gelöscht (über diese API oder durch Ablauf der Aufbewahrungsrichtlinie) oder gehört zu einer Organisation außerhalb des Scopes deines Keys.

Datei nicht gefunden

Type: not_found_error

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

Ursache: Die File-ID existiert nicht oder wurde gelöscht. Dieser Fehler gilt sowohl für an Chats angehängte Dateien (claude_file_...) als auch für Projektdateien.

Lösung: Gleiche mit aktuellen claude_file_uploaded- oder claude_file_deleted-Aktivitäten ab. Wenn die Datei gelöscht wurde, ist die Binärdatei weg; der Aktivitätsdatensatz bleibt im Feed für das 6-jährige Aufbewahrungsfenster erhalten.

Projekt nicht gefunden

Type: not_found_error

No project is found with the provided id.

Ursache: Die Projekt-ID existiert nicht oder wurde gelöscht.

Lösung: Gleiche mit aktuellen claude_project_created- oder claude_project_deleted-Aktivitäten ab. Der Activity Feed stellt die Lebenszyklus-Ereignisse des Projekts weiterhin bereit, auch nachdem das Projekt selbst nicht mehr existiert.

Projektdokument nicht gefunden

Type: not_found_error

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

Ursache: Die Projektdokument-ID existiert nicht oder wurde gelöscht. Dieser Fehler gilt für Text-Projektdokumente (claude_proj_doc_...), nicht für Projektdateien.

Lösung: Verwende GET /v1/compliance/apps/projects/{project_id}/attachments, um aktuelle Anhänge aufzulisten. Wenn das Dokument fehlt, wurde es gelöscht; rufe es über einen claude_project_document_uploaded-Aktivitätsdatensatz ab, wenn du nur die Metadaten benötigst.

Organisation, Rolle oder Gruppe nicht gefunden

Type: not_found_error

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

Die Organisations-, Rollen- und Gruppen-Endpunkte geben einen 404 not_found_error im Standard-Fehlerformat zurück. Die Organisations-Message nennt die org_uuid; die Rollen- und Gruppen-Messages sind generisch (Role not found., Group not found.). Dies tritt auf, wenn eine Pfad-ID (org_uuid, role_id oder group_id) nicht existiert oder nicht mehr zu einem Baum gehört, den der aufrufende Key lesen kann.

Ursache: Die ID im Pfad stimmt mit keinem Datensatz überein, der über die Compliance API lesbar ist. Rollen und Gruppen können gelöscht werden, und Organisationen können vom übergeordneten Baum getrennt werden.

Lösung: Verifiziere die ID anhand des entsprechenden List-Endpunkts und gleiche mit aktuellen Organisations-, Rollen- oder Gruppenaktivitäten im Activity Feed ab.

409 Conflict

Die Anfrage ist wohlgeformt und autorisiert, steht aber im Konflikt mit dem aktuellen Zustand der Ressource.

Projekt hat angehängte Chats

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.

Ursache: DELETE /v1/compliance/apps/projects/{project_id} wurde für ein Projekt aufgerufen, das noch angehängte Chats hat.

Lösung: Liste die Chats des Projekts mit GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} auf (der Chat-List-Endpunkt erfordert mindestens einen user_ids[]-Wert; ermittle IDs über Organisationsbenutzer auflisten), lösche jeden einzelnen mit DELETE /v1/compliance/apps/chats/{claude_chat_id} und versuche dann das Löschen des Projekts erneut.

429 Too Many Requests

Anfragen an die Compliance API sind auf 600 Anfragen pro Minute pro übergeordneter Organisation begrenzt. Das Limit ist ein einzelnes Budget, das über alle Keys unter der übergeordneten Organisation (Compliance Access Keys und die Admin API-Keys aller verknüpften Organisationen) und über alle /v1/compliance/*-Endpunkte geteilt wird. Kontaktiere deinen Anthropic-Ansprechpartner, wenn deine Integration ein höheres Limit benötigt.

Sobald dein API-Key authentifiziert ist, enthält jede Compliance API-Antwort die standardmäßigen Ratenlimit-Response-Header, damit dein Client proaktiv drosseln kann, anstatt auf ein 429 zu warten:

• anthropic-ratelimit-requests-limit ist das Anfragebudget pro Minute deiner übergeordneten Organisation.
• anthropic-ratelimit-requests-remaining ist das verbleibende Budget im aktuellen Fenster.
• anthropic-ratelimit-requests-reset ist der RFC 3339-Zeitstempel, zu dem das Fenster zurückgesetzt und das volle Budget wiederhergestellt wird.

Eine 429-Antwort trägt auch einen retry-after-Header mit der Anzahl der Sekunden, die gewartet werden soll, bevor die nächste Anfrage gesendet wird. Dieser Wert kann einen kleinen Sicherheitspuffer über anthropic-ratelimit-requests-reset hinaus enthalten; beachte 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."
  }
}

Ursache: Deine übergeordnete Organisation hat mehr als 600 Anfragen an /v1/compliance/* in einem 1-Minuten-Fenster gesendet, über alle ihre Keys und verknüpften Organisationen hinweg.

Lösung: Warte die Anzahl der Sekunden im retry-after-Header, dann versuche es erneut. Wenn der Header fehlt (zum Beispiel durch einen Intermediär entfernt), greife auf exponentielles Backoff zurück (beginne bei 1 Sekunde, verdopple bis zu 60 Sekunden). Rücke deinen Paginierungs-Cursor bei einem 429 nicht vor: Die fehlgeschlagene Anfrage hat keine Daten zurückgegeben, daher ist der Cursor von der letzten erfolgreichen Seite noch korrekt.

Anfragen, die bei der Authentifizierung fehlschlagen (ein fehlender oder nicht erkannter Key oder ein Claude API-Key anstelle eines Compliance Access Keys oder Admin API-Keys), werden vor dem Rate-Limiter abgelehnt und verbrauchen kein Kontingent. Ein gültiger Key, dem der erforderliche Scope des Endpunkts fehlt, verbraucht eine Kontingenteinheit, bevor das 403 zurückgegeben wird.

Wenn du den Activity Feed nach einem Zeitplan abfragst, plane deine aggregierte Anfragerate (über alle Keys, verknüpften Organisationen und gleichzeitigen Worker) unterhalb des Limits der übergeordneten Organisation. Beobachte anthropic-ratelimit-requests-remaining, um zu verlangsamen, bevor du es erreichst. Siehe Deine Compliance-Integration entwerfen für die Wahl zwischen Window-Polling und Cursor-gesteuerter Erfassung.

500 Internal Server Error

Ein 500 von der Compliance API trägt einen x-should-retry: false-Response-Header, wenn der Fehler deterministisch ist. Anthropic-SDKs beachten diesen Header automatisch. Wenn du eine generische HTTP-Retry-Bibliothek verwendest, die bei jedem 5xx einen Retry durchführt, unterdrücke Retries, wenn x-should-retry false ist; ein Retry dieses Fehlers schlägt bei jedem Versuch identisch fehl.

Ein 500 ohne den x-should-retry: false-Header ist vorübergehend: Versuche es erneut mit exponentiellem Backoff (beginne bei 1 Sekunde, verdopple bis zu 60 Sekunden). Dasselbe gilt für 502-, 503-, 504- und 529-Antworten. Siehe Fehler für die plattformweite Retry-Semantik.

Für dienstweite Vorfälle prüfe status.anthropic.com.

Maximale Antwortgröße überschritten

Type: api_error

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

Ursache: Ein List-Endpunkt ohne Paginierung (insbesondere GET /v1/compliance/organizations) hätte mehr als seine harte Obergrenze von 1.000 Datensätzen zurückgegeben.

Lösung: Der Organisations-Endpunkt gibt den vollständigen Baum in einem Aufruf zurück, bis zu 1.000 verknüpfte Organisationen. Wenn dein Baum 1.000 überschreitet, kontaktiere den Anthropic-Support für Unterstützung bei größeren Organisationslisten. Wenn du diesen Endpunkt abgefragt hast, um Änderungen der Organisationsmitgliedschaft zu verfolgen, bleibt periodisches erneutes Auflisten der zuverlässigste Ansatz, sobald die Obergrenze behoben ist; es erfasst Hinzufügungen und Entfernungen unabhängig davon, welche Seite der Parent-Child-Beziehung sie initiiert hat. Der Activity Feed zeigt Mitgliedschaftsereignisse auch über die Activity-Types org_deletion_requested, org_deleted_via_bulk, org_parent_join_proposal_created und org_join_proposal_decided an, die du verwenden kannst, um ein sofortiges erneutes Auflisten auszulösen, anstatt auf das nächste Polling-Intervall zu warten.

Nächste Schritte