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 in un formato coerente con il resto del formato degli errori 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 inoltri la segnalazione al supporto.

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

Effettua il matching 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 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 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 interpretato come datetime. Il messaggio indica il parametro che ha causato l'errore e riporta il valore 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.

Limite 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 l'endpoint specifico 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é interpretato 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 (utenti, ruoli, permessi dei ruoli, gruppi, membri dei gruppi, progetti e allegati dei progetti) paginano 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 errati 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. Consulta Ottenere l'accesso alla 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; consulta Dopo l'abilitazione: organizzazioni Claude Console.

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. Consulta 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 o 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_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 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 dovrebbe davvero riguardare solo l'Activity Feed, indirizza la chiave Admin API verso 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; consulta 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 popolato.

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) o appartiene a un'organizzazione al di fuori dello scope 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 di progetto.

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 è stato rimosso.

Documento di 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 di progetto non esiste o è stato eliminato. Questo errore si applica ai documenti di progetto testuali (claude_proj_doc_...), non ai file di progetto.

Soluzione: Usa GET /v1/compliance/apps/projects/{project_id}/attachments per elencare gli allegati correnti. Se il documento è mancante, è 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 organizzazione, ruolo e gruppo 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. Ruoli e 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.

409 Conflict

La richiesta è ben formata e autorizzata ma è in conflitto con lo stato corrente 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} (l'endpoint di elenco delle chat 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}, quindi 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 unico budget condiviso tra tutte le chiavi sotto l'organizzazione padre (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ò limitare proattivamente le richieste 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 reimposta 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, attraverso tutte le sue chiavi e 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 avanzare il 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 API di Claude anziché una Compliance Access Key o una chiave Admin API) vengono rifiutate prima del rate limiter 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 periodicamente l'Activity Feed, pianifica il tuo tasso di richieste aggregato (attraverso tutte le chiavi, organizzazioni collegate e worker concorrenti) al di sotto del limite dell'organizzazione padre. Monitora anthropic-ratelimit-requests-remaining per rallentare prima di raggiungerlo. Consulta Progettare la tua integrazione di compliance per scegliere tra polling a finestra e ingestione basata su 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. Consulta Errori per la semantica di retry a livello di piattaforma.

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

Dimensione massima della risposta superata

Type: api_error

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

Causa: Un endpoint di elenco senza paginazione (in particolare GET /v1/compliance/organizations) avrebbe restituito più del suo limite massimo di 1.000 record.

Soluzione: L'endpoint delle organizzazioni restituisce l'intero albero in una singola chiamata, fino a 1.000 organizzazioni collegate. Se il tuo albero supera le 1.000, contatta il supporto Anthropic per assistenza con elenchi di organizzazioni più grandi. Se stavi interrogando periodicamente questo endpoint per tracciare le modifiche all'appartenenza delle organizzazioni, il rielenco periodico rimane l'approccio più affidabile una volta risolto il limite; rileva aggiunte e rimozioni indipendentemente da quale lato della relazione padre-figlio le abbia avviate. L'Activity Feed espone anche gli eventi di appartenenza tramite i tipi di attività org_deletion_requested, org_deleted_via_bulk, org_parent_join_proposal_created e org_join_proposal_decided, che puoi usare per attivare un rielenco immediato invece di attendere il prossimo intervallo di polling.

Passaggi successivi