Gestire gli errori della Compliance API

Questa pagina elenca i messaggi di risposta restituiti da ciascun endpoint documentato della Compliance API, la causa e la soluzione.

La Compliance API restituisce gli errori nel formato di errore standard di Anthropic: un codice di stato non-2xx, un header di risposta request-id e un corpo JSON con un oggetto error contenente type e message. Includi il valore dell'header request-id quando effettui un'escalation al supporto.

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

Effettua il match su error.type, non sulla stringa del messaggio. I messaggi sono abbastanza stabili da poter essere copiati nei runbook, ma potrebbero essere riformulati nel tempo; i valori di type fanno parte del contratto dell'API.

La tabella seguente ti indica a colpo d'occhio se riprovare. Ogni sezione successiva mostra il corpo dell'errore letterale e la soluzione.



400 Bad Request

La richiesta era sintatticamente valida ma conteneva un parametro che il server ha rifiutato. Correggi il parametro e riprova.



Formato del timestamp non valido

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

Causa: Un valore created_at.* o updated_at.* (.gte, .gt, .lte, .lt) non è stato analizzato come datetime. Il messaggio indica il nome del parametro che ha fallito e riporta il valore che è stato inviato.

Soluzione: Invia un timestamp RFC 3339 completo che includa ora e fuso orario, ad esempio 2024-03-01T00:00:00Z o 2024-03-01T00:00:00+00:00.



Limit non valido

Type: invalid_request_error

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

Causa: Il parametro di query limit era al di fuori dell'intervallo accettato. Il limite indicato nel messaggio riflette il massimo per lo specifico endpoint che è stato chiamato.

Soluzione: Invia un limit all'interno dell'intervallo accettato dall'endpoint. Ogni endpoint di elenco ha il proprio intervallo di limit; consulta i vincoli dei parametri nella pagina corrispondente del riferimento della Compliance API.



ID di paginazione non valido

Type: invalid_request_error

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

Causa: Il cursore after_id o before_id non è stato decodificato come cursore opaco né analizzato come ID di attività.

Soluzione: Tratta i cursori di paginazione come stringhe opache. Copia sempre il valore first_id o last_id restituito dalla pagina precedente; fermati quando has_more è false. Non costruire cursori a partire dagli ID degli oggetti.

Gli endpoint di directory e progetti (organizzazioni, utenti, ruoli, permessi dei ruoli, gruppi, membri dei gruppi, progetti e allegati dei progetti) effettuano la paginazione con un token page opaco anziché con after_id e before_id. Vale lo stesso consiglio: passa il valore next_page della risposta precedente senza modificarlo e fermati quando has_more è false. Un token page malformato restituisce lo stesso 400 invalid_request_error di un after_id o before_id malformato.



401 Unauthorized

L'header x-api-key era mancante o non corrispondeva a una chiave nota. Una chiave valida con gli scope sbagliati restituisce invece 403 Forbidden.



Chiave API non valida

Type: authentication_error

The API key provided is invalid or has been revoked.

Causa: La chiave in x-api-key non esiste, è stata eliminata o è stata disabilitata. Un header x-api-key mancante o vuoto restituisce lo stesso corpo, quindi controlla sia il tuo archivio dei segreti sia lo stato di revoca della chiave.

Soluzione: Conferma il valore della chiave, verifica che non sia stata eliminata in claude.ai (Compliance Access Keys) o in Claude Console (chiavi Admin API) e conferma che sia abilitata. Vedi Configurare la Compliance API.



403 Forbidden

La chiave in x-api-key è valida ma non possiede lo scope richiesto dall'endpoint. Il messaggio letterale elenca gli scope posseduti dalla chiave (Got:) e gli scope richiesti dall'endpoint (Needed:), così puoi confermare cosa possiede la chiave senza ricontrollare Claude Console o claude.ai. Gli scope delle Compliance Access Key sono immutabili dopo la creazione, quindi ogni soluzione per scope insufficiente ti indirizza a creare una nuova chiave anziché modificare quella esistente.



Scope insufficiente: Activity Feed

Type: permission_error

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

Causa: Una chiave senza read:compliance_activities è stata usata per chiamare GET /v1/compliance/activities. Ci sono due percorsi comuni che portano a questo errore:

• Una Compliance Access Key (sk-ant-api01-...) è stata creata senza lo scope read:compliance_activities.
• Una chiave Admin API di Claude Console (sk-ant-admin01-...) è stata creata prima che la Compliance API fosse abilitata per l'organizzazione. Le chiavi create prima dell'abilitazione non possiedono lo scope; vedi Configurare la Compliance API.

Soluzione: Gli scope delle Compliance Access Key sono immutabili dopo la creazione. Crea una nuova chiave che includa read:compliance_activities, oppure usa una chiave Admin API di Claude Console. Vedi Quale chiave ti serve? per le condizioni in cui una chiave Admin API possiede questo scope.



Scope insufficiente: dati dell'organizzazione

Type: permission_error

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

Causa: Una chiave senza read:compliance_org_data è stata usata per chiamare un endpoint di organizzazioni, ruoli, gruppi o impostazioni effettive. Ci sono due percorsi comuni che portano a questo errore:

• Una Compliance Access Key (sk-ant-api01-...) è stata creata senza lo scope read:compliance_org_data.
• È stata usata una chiave Admin API di Claude Console (sk-ant-admin01-...). Le chiavi Admin API possiedono solo read:compliance_activities e non possono leggere i metadati dell'organizzazione.

Soluzione: Crea una nuova Compliance Access Key con read:compliance_org_data selezionato. Le chiavi Admin API non possono leggere i metadati dell'organizzazione; è richiesta la Compliance Access Key.



Scope ritirato: impostazioni dell'organizzazione

Type: permission_error

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

Causa: Lo scope read:compliance_org_settings è stato ritirato il 30 giugno 2026. GET /v1/compliance/organizations/{organization_id}/settings ora richiede read:compliance_org_data, lo stesso scope degli altri endpoint dell'organizzazione, e lo scope ritirato non autorizza più nulla. Una Compliance Access Key che possiede solo read:compliance_org_settings restituisce questo errore a ogni chiamata all'endpoint delle impostazioni, anche se la chiave funzionava prima del ritiro. Lo scope ritirato non può più essere selezionato o concesso durante la creazione di una chiave.

Soluzione: Gli scope delle Compliance Access Key sono immutabili dopo la creazione. Crea una nuova Compliance Access Key con read:compliance_org_data selezionato, aggiorna la tua integrazione per usarla, poi elimina la vecchia chiave. Una chiave che possiede già read:compliance_org_data non è interessata dal ritiro.



Scope insufficiente: dati utente

Type: permission_error

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

Causa: Una chiave senza read:compliance_user_data è stata usata per chiamare un endpoint di chat, messaggi, file, progetti, utenti dell'organizzazione, o membri dei gruppi. Ci sono due percorsi comuni che portano a questo errore:

• Una Compliance Access Key (sk-ant-api01-...) è stata creata senza lo scope read:compliance_user_data.
• È stata usata una chiave Admin API di Claude Console (sk-ant-admin01-...). Le chiavi Admin API possiedono solo read:compliance_activities e non possono ricevere read:compliance_user_data, quindi non possono chiamare gli endpoint di chat, file, progetti, allegati dei progetti, utenti, o membri dei gruppi.

Soluzione: Usa una Compliance Access Key creata in claude.ai con read:compliance_user_data selezionato. Se la richiesta deve davvero riguardare solo l'Activity Feed, indirizza invece la chiave Admin API a GET /v1/compliance/activities.



Scope insufficiente: eliminazione

Type: permission_error

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

Causa: Una Compliance Access Key senza delete:compliance_user_data è stata usata per chiamare un endpoint DELETE su chat, file o progetti.

Soluzione: Crea una nuova Compliance Access Key con delete:compliance_user_data selezionato. Lo scope di eliminazione è separato da read:compliance_user_data in modo che le chiavi di audit in sola lettura non possano eliminare contenuti.



404 Not Found

L'endpoint è stato risolto ma l'ID della risorsa non esiste o è già stato eliminato. Le eliminazioni della Compliance API sono immediate e permanenti, quindi un 404 su un ID precedentemente noto di solito significa che il contenuto è stato eliminato definitivamente tramite una chiamata di eliminazione della Compliance API o rimosso da una policy di conservazione. Le stringhe dei tipi di attività citate in ogni Soluzione (ad esempio, claude_chat_created) sono valori che puoi passare al filtro activity_types[] dell'Activity Feed; vedi Interrogare le attività di compliance per tutti i valori supportati.



Chat non trovata

Type: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

Causa: L'ID della chat nel percorso non corrisponde a una chat leggibile tramite la Compliance API. La chat potrebbe essere stata eliminata definitivamente tramite una precedente chiamata alla Compliance API o rimossa dalla policy di conservazione della tua organizzazione, oppure potrebbe appartenere a un'organizzazione che la chiave chiamante non può leggere. Le chat che un utente ha eliminato in modo soft in claude.ai non restituiscono 404; rimangono leggibili con deleted_at valorizzato.

Soluzione: Conferma l'ID della chat rispetto a un'attività recente claude_chat_created o claude_chat_viewed. Se l'attività è recente e la lettura continua a fallire, la chat è stata eliminata definitivamente (tramite questa API o per scadenza della policy di conservazione) oppure appartiene a un'organizzazione al di fuori dell'ambito della tua chiave.



File non trovato

Type: not_found_error

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

Causa: L'ID del file non esiste o è stato eliminato. Questo errore si applica sia ai file allegati alle chat (claude_file_...) sia ai file dei progetti.

Soluzione: Riconcilia rispetto alle attività recenti claude_file_uploaded o claude_file_deleted. Se il file è stato eliminato, il binario non esiste più; il record dell'attività rimane nel feed per la finestra di conservazione di 6 anni.



Progetto non trovato

Type: not_found_error

No project is found with the provided id.

Causa: L'ID del progetto non esiste o è stato eliminato.

Soluzione: Riconcilia rispetto alle attività recenti claude_project_created o claude_project_deleted. L'Activity Feed continua a esporre gli eventi del ciclo di vita del progetto anche dopo che il progetto stesso non esiste più.



Documento del progetto non trovato

Type: not_found_error

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

Causa: L'ID del documento del progetto non esiste o è stato eliminato. Questo errore si applica ai documenti di testo dei progetti (claude_proj_doc_...), non ai file dei progetti.

Soluzione: Usa GET /v1/compliance/apps/projects/{project_id}/attachments per elencare gli allegati attuali. Se il documento manca, è stato eliminato; recuperalo tramite un record di attività claude_project_document_uploaded se ti servono solo i metadati.



Organizzazione, ruolo o gruppo non trovato

Type: not_found_error

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

Gli endpoint di organizzazioni, ruoli e gruppi restituiscono un 404 not_found_error nel formato di errore standard. Il messaggio dell'organizzazione indica l'org_uuid; i messaggi di ruolo e gruppo sono generici (Role not found., Group not found.). Questo si verifica quando un ID nel percorso (org_uuid, role_id o group_id) non esiste o non appartiene più a un albero che la chiave chiamante può leggere.

Causa: L'ID nel percorso non corrisponde a un record leggibile tramite la Compliance API. I ruoli e i gruppi possono essere eliminati, e le organizzazioni possono essere scollegate dall'albero padre.

Soluzione: Verifica l'ID rispetto all'endpoint di elenco corrispondente e riconcilia rispetto alle attività recenti di organizzazione, ruolo o gruppo nell'Activity Feed.



Impostazioni dell'organizzazione non disponibili

Type: not_found_error

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

Causa: GET /v1/compliance/organizations/{organization_id}/settings restituisce questo 404 in tre casi che condividono intenzionalmente lo stesso corpo in modo che la risposta non riveli se un'organizzazione esiste: l'organization_id non è una delle organizzazioni collegate al tuo padre, il valore non è un UUID valido, oppure l'endpoint delle impostazioni non è ancora abilitato per la tua organizzazione padre.

Soluzione: Verifica l'ID rispetto a Elencare le organizzazioni. Se un ID di organizzazione noto come valido restituisce ancora 404, l'endpoint delle impostazioni non è ancora abilitato per la tua organizzazione padre; contatta il tuo referente Anthropic.



409 Conflict

La richiesta è ben formata e autorizzata ma è in conflitto con lo stato attuale della risorsa.



Il progetto ha chat allegate

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.

Causa: DELETE /v1/compliance/apps/projects/{project_id} è stato chiamato su un progetto che ha ancora chat allegate.

Soluzione: Elenca le chat del progetto con GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} (il filtro project_ids[] richiede almeno un valore user_ids[]; enumera gli ID tramite Elencare gli utenti dell'organizzazione), elimina ciascuna con DELETE /v1/compliance/apps/chats/{claude_chat_id}, e poi riprova l'eliminazione del progetto.



429 Too Many Requests

Le richieste alla Compliance API sono limitate a 600 richieste al minuto per organizzazione padre. Il limite è un singolo budget condiviso tra tutte le chiavi sotto il padre (le Compliance Access Key e le chiavi Admin API di tutte le organizzazioni collegate) e tra tutti gli endpoint /v1/compliance/*. Contatta il tuo referente Anthropic se la tua integrazione necessita di un limite più alto.

Una volta che la tua chiave API si autentica, ogni risposta della Compliance API include gli header di risposta del limite di velocità standard, così il tuo client può rallentare in modo proattivo invece di attendere un 429:

• anthropic-ratelimit-requests-limit è il budget di richieste al minuto della tua organizzazione padre.
• anthropic-ratelimit-requests-remaining è il budget rimanente nella finestra corrente.
• anthropic-ratelimit-requests-reset è il timestamp RFC 3339 in cui la finestra si azzera e il budget completo viene ripristinato.

Una risposta 429 include anche un header retry-after con il numero di secondi da attendere prima di inviare la richiesta successiva. Questo valore potrebbe includere un piccolo margine di sicurezza oltre anthropic-ratelimit-requests-reset; rispetta 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."
  }
}

Causa: La tua organizzazione padre ha inviato più di 600 richieste a /v1/compliance/* in una finestra di 1 minuto, considerando tutte le sue chiavi e le organizzazioni collegate.

Soluzione: Attendi il numero di secondi indicato nell'header retry-after, poi riprova. Se l'header è assente (ad esempio, rimosso da un intermediario), ricorri al backoff esponenziale (inizia da 1 secondo, raddoppia fino a 60 secondi). Non far avanzare il tuo cursore di paginazione su un 429: la richiesta fallita non ha restituito dati, quindi il cursore dell'ultima pagina riuscita è ancora corretto.

Le richieste che falliscono l'autenticazione (una chiave mancante o non riconosciuta, oppure una chiave Claude API anziché una Compliance Access Key o una chiave Admin API) vengono rifiutate prima del limitatore di velocità e non consumano quota. Una chiave valida che non possiede lo scope richiesto dall'endpoint consuma un'unità di quota prima che venga restituito il 403.

Se interroghi l'Activity Feed in modo pianificato, mantieni il tuo tasso di richieste aggregato (tra tutte le chiavi, le organizzazioni collegate e i worker concorrenti) al di sotto del limite dell'organizzazione padre. Osserva anthropic-ratelimit-requests-remaining per rallentare prima di raggiungerlo. Vedi Progettare la tua integrazione di compliance per scegliere tra il polling a finestre e l'ingestione guidata da cursore.



500 Internal Server Error

Un 500 dalla Compliance API include un header di risposta x-should-retry: false quando il fallimento è deterministico. Gli SDK di Anthropic rispettano automaticamente questo header. Se usi una libreria HTTP generica di retry che riprova su ogni 5xx, sopprimi i retry quando x-should-retry è false; riprovare questo errore fallisce in modo identico a ogni tentativo.

Un 500 senza l'header x-should-retry: false è transitorio: riprova con backoff esponenziale (inizia da 1 secondo, raddoppia fino a 60 secondi). Lo stesso vale per le risposte 502, 503, 504 e 529. Vedi Errori per la semantica di retry a livello di piattaforma.

Per gli incidenti a livello di servizio, controlla status.anthropic.com.



Prossimi passi