Gestire gli errori della Compliance API

Questa pagina elenca le risposte di errore comuni della Compliance API per codice di stato HTTP, con la causa e la soluzione per ciascuna.

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 ti rivolgi al supporto.

{
  "error": {
    "type": "permission_error",
    "message": "Missing required scopes. Got: ['read:compliance_activities'] Needed one of: ['read:compliance_user_data', 'read:org_audit']"
  }
}

In questa pagina, le sessioni locali vengono eseguite sui computer degli utenti e le sessioni remote vengono eseguite nel cloud; consulta Recuperare le trascrizioni delle sessioni.

Basati sul codice di stato HTTP e 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 codici di stato e i valori di type fanno parte del contratto dell'API. Alcune risposte che condividono lo stesso codice di stato e lo stesso tipo si distinguono tramite un codice di errore in error.details.error_code quando la risposta ne contiene uno, e altrimenti tramite il loro messaggio; ciascuna viene segnalata dove pertinente.

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

400 Bad Request

La richiesta era sintatticamente valida, ma il server ha rifiutato un parametro oppure la Compliance API non è abilitata per l'organizzazione. Correggi la causa indicata nel messaggio e invia di nuovo. Un 400 fa eccezione: Pagina della trascrizione troppo grande, che l'endpoint dei messaggi delle sessioni locali può restituire per una pagina di una sessione molto grande anche quando tutti i parametri sono validi; la sua voce spiega cosa fare invece di inviare di nuovo.

Compliance API non abilitata

Tipo: invalid_request_error

Compliance API is not enabled for this organization

Causa: La chiave è valida, ma la Compliance API non è abilitata per l'organizzazione o l'organizzazione padre a cui appartiene la chiave. Ogni endpoint restituisce questa risposta finché l'API non viene abilitata, e di nuovo se un amministratore disattiva l'API.

Soluzione: Abilita la Compliance API seguendo Configurare la Compliance API, quindi invia di nuovo la richiesta.

Parametro di query sconosciuto

Tipo: invalid_request_error

Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'?

Causa: La richiesta includeva un parametro di query che l'endpoint non definisce; la Compliance API rifiuta i parametri non riconosciuti anziché ignorarli. Il messaggio nomina il parametro e, per i casi molto simili come la notazione con parentesi quadre al posto del punto o un suffisso [] mancante, suggerisce il nome definito.

Soluzione: Usa i nomi dei parametri mostrati nella pagina del riferimento della Compliance API relativa all'endpoint. I filtri di intervallo usano la notazione con il punto (ad esempio, created_at.gte), i filtri di array richiedono un suffisso [] (ad esempio, activity_types[]) e i parametri di paginazione sono after_id, before_id o page, a seconda dell'endpoint.

Valore del parametro non valido

Tipo: invalid_request_error

limit: Input should be less than or equal to 1000

created_at.gte: Input should be a valid datetime or date, invalid character in year

activity_types[].0: Input is not one of the permitted values.

Causa: Il valore di un parametro di query non ha superato la convalida. Il messaggio inizia con il nome del parametro (seguito dalla posizione dell'elemento per un parametro di tipo array), quindi indica il vincolo non rispettato. Sono mostrati tre casi comuni: un limit superiore al massimo dell'endpoint (il numero nel messaggio è il massimo di quell'endpoint), un valore created_at.* o updated_at.* che non può essere interpretato come data o timestamp, e un valore activity_types[] che non è un tipo di attività supportato.

Soluzione: Correggi il parametro indicato nel messaggio. Ogni endpoint di elenco ha il proprio intervallo per limit; consulta i vincoli dei parametri nella pagina corrispondente del riferimento della Compliance API. Invia i timestamp in formato RFC 3339 con un offset UTC esplicito, ad esempio 2024-03-01T00:00:00Z o 2024-03-01T00:00:00+00:00; l'elenco delle sessioni locali rifiuta un timestamp senza offset (created_at.gte: Input should have timezone info). Per i valori activity_types[] supportati, consulta Interrogare le attività di conformità.

L'elenco delle sessioni locali (GET /v1/compliance/apps/sessions/local) restituisce inoltre un 400 invalid_request_error quando fornisci un limite inferiore (created_at.gte o created_at.gt) e un limite superiore (created_at.lt o created_at.lte) e il limite superiore non è successivo al limite inferiore. Limiti uguali sono consentiti solo per created_at.gte con created_at.lte. Il messaggio nomina i due parametri, ad esempio:

created_at.lt must be strictly after created_at.gte.

created_at.lte must be at or after created_at.gte.

Invia un limite superiore successivo al limite inferiore, oppure ometti uno dei due limiti.

Gli endpoint delle trascrizioni delle sessioni (GET /v1/compliance/apps/sessions/local/{session_id}/messages e GET /v1/compliance/apps/sessions/remote/{session_id}/messages) convalidano i propri parametri di troncamento allo stesso modo: tool_use_input_max_bytes e tool_result_max_bytes accettano ciascuno un numero positivo di byte oppure -1 (il massimo del server), quindi un valore come 0 restituisce lo stesso 400 invalid_request_error.

Cursore di paginazione non valido

Tipo: invalid_request_error

Invalid activity_id format: 'activity_invalid123'

Invalid pagination cursor for 'after_id'

Causa: Non è stato possibile decodificare un "pagination cursor" (cursore di paginazione). Nell'Activity Feed, un valore after_id o before_id che non è né un cursore emesso dall'API né un ID di attività ben formato restituisce il primo corpo, che riporta il valore inviato. Sugli endpoint delle chat e dei messaggi delle chat, un valore after_id o before_id che non può essere decodificato restituisce il secondo corpo, che nomina il parametro.

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, progetti e sessioni (organizzazioni, utenti, ruoli, permessi dei ruoli, gruppi, membri dei gruppi, progetti, allegati dei progetti, sessioni locali e remote e messaggi delle sessioni) paginano con un token page opaco anziché con after_id e before_id. Vale lo stesso consiglio: passa invariato il valore next_page della risposta precedente e fermati quando has_more è false (oppure, sugli endpoint delle sessioni, che non restituiscono has_more, quando next_page è null). Un token page malformato restituisce lo stesso 400 invalid_request_error di un after_id o before_id malformato, con un messaggio specifico per l'endpoint.

I due endpoint paginati delle sessioni locali (l'elenco e l'endpoint dei messaggi) restituiscono il seguente 400 invalid_request_error per qualsiasi valore page che non riescono a decodificare, ad esempio un token troncato o alterato dopo che lo hai memorizzato, oppure uno emesso da un endpoint diverso o per un'organizzazione padre diversa. Sull'endpoint dei messaggi delle sessioni locali (GET /v1/compliance/apps/sessions/local/{session_id}/messages), ogni cursore page è inoltre vincolato alla sessione e all'order per cui è stato emesso, quindi un cursore emesso per una sessione o un ordinamento diversi restituisce lo stesso corpo:

The page parameter is not a valid cursor for this request.

I cursori sull'endpoint dei messaggi scadono inoltre 24 ore dopo l'inizio della scansione (un passaggio completo attraverso le pagine). Un cursore scaduto restituisce:

The page cursor has expired. Restart the walk without a page parameter; results will reflect the current retention boundary.

Per il primo corpo, invia di nuovo il valore next_page non modificato della risposta precedente all'endpoint e alla sessione che lo hanno emesso. Per un cursore scaduto, ricomincia senza un parametro page; la nuova scansione riflette il limite di conservazione in vigore al momento del suo avvio, quindi i messaggi che nel frattempo sono usciti dal periodo di conservazione non vengono più restituiti (consulta Recuperare la trascrizione di una sessione locale).

Pagina della trascrizione troppo grande

Tipo: invalid_request_error

Codice di errore: transcript_page_read_limit_exceeded, restituito in error.details.error_code

This page of the session's transcript is too large to read, and retrying will not help. If you are reading newest first (order=desc), read this session oldest first instead: omit the order and page parameters, then follow next_page.

Causa: GET /v1/compliance/apps/sessions/local/{session_id}/messages può restituire questo errore per una pagina di una sessione molto grande. Solo questo endpoint restituisce questo errore. Condivide il tipo invalid_request_error con gli altri 400, quindi identificalo tramite il suo codice di errore, non tramite il testo del messaggio, che potrebbe essere riformulato.

Soluzione: Non riprovare la richiesta. Se usava order=desc, leggi invece quella sessione dal messaggio più vecchio:

• Ricomincia la scansione della sessione (un passaggio attraverso le sue pagine; consulta Recuperare la trascrizione di una sessione locale) senza order (o con order=asc) e senza page, e segui next_page finché non è null. I messaggi che hai già memorizzato dalla lettura dal più recente mantengono lo stesso id, quindi deduplica in base a id.
• Imposta il timeout delle richieste del tuo client ad almeno 5 minuti per questa scansione.
• Ridurre limit non è un modo affidabile per evitare questo errore.

Se una richiesta dal più vecchio restituisce questo errore, non riprovare nemmeno quella. Conserva le pagine che hai già letto, registra la sessione come incompleta, continua con il resto dell'esportazione e contatta il tuo referente Anthropic indicando l'header di risposta request-id.

401 Unauthorized

La richiesta conteneva una Compliance Access Key (sk-ant-api01-...) o una chiave Admin API (sk-ant-admin01-...) che non supera l'autenticazione. Una richiesta che non contiene alcuna chiave, o che contiene una chiave di un altro tipo, restituisce invece 404 Not Found su ogni endpoint tranne le impostazioni dell'organizzazione, e una chiave valida con gli scope errati restituisce 403 Forbidden.

Chiave API non valida, disattivata o scaduta

Tipo: authentication_error

API key is invalid.

API key has been deactivated.

API key has expired.

Causa: API key is invalid. significa che il valore inviato non corrisponde a una chiave utilizzabile, ad esempio perché è stato troncato o alterato al momento della memorizzazione. API key has been deactivated. significa che la chiave è stata disabilitata o eliminata. API key has expired. significa che la data di scadenza di una chiave Admin API è passata; le Compliance Access Key non vengono create con una data di scadenza.

Soluzione: Per API key is invalid., confronta il valore inviato dal tuo client con il segreto che hai memorizzato al momento della creazione della chiave; il segreto completo viene mostrato una sola volta, quindi se la copia memorizzata è errata, crea una nuova chiave. Per API key has been deactivated., riattiva la chiave se era solo disabilitata, in claude.ai > Impostazioni organizzazione > API per una Compliance Access Key oppure nella pagina Chiavi admin (platform.claude.com/settings/admin-keys) nella Claude Console per una chiave Admin API; una chiave eliminata non può essere ripristinata. Per una chiave eliminata o scaduta, crea una nuova chiave e aggiorna la tua integrazione per usarla, come descritto in Gestire e ruotare le chiavi.

403 Forbidden

La chiave in x-api-key è valida ma non include uno scope accettato dall'endpoint. Il messaggio testuale elenca gli scope inclusi nella chiave (Got:) e gli scope accettati dall'endpoint (Needed one of: sugli endpoint di lettura, dove è sufficiente uno qualsiasi degli scope elencati, oppure Needed: sugli endpoint di eliminazione), così puoi verificare cosa include la chiave senza ricontrollare Claude Console o claude.ai. Sugli endpoint di lettura, l'elenco degli scope accettati include anche read:org_audit, uno scope di audit in sola lettura che copre ogni endpoint di lettura della Compliance API; consulta Scegliere gli scope per una chiave Claude Enterprise. Gli scope di una Compliance Access Key sono immutabili dopo la creazione, quindi ogni soluzione per scope insufficienti ti indica di creare una nuova chiave anziché modificare quella esistente. Un'organizzazione Claude Console autonoma (senza organizzazione padre) non può creare una Compliance Access Key, quindi le soluzioni che ne richiedono una non si applicano a essa; può interrogare solo l'Activity Feed.

Scope insufficiente: Activity Feed

Tipo: permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed one of: ['read:compliance_activities', 'read:org_audit']

Causa: Una chiave senza read:compliance_activities è stata usata per chiamare GET /v1/compliance/activities. Esistono 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 mentre la Compliance API non era abilitata per l'organizzazione. Le chiavi create mentre la Compliance API non era abilitata non includono lo scope; consulta Configurare la Compliance API.

Soluzione: Gli scope di una 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 Di quale chiave hai bisogno? per le condizioni in cui una chiave Admin API include questo scope.

Scope insufficiente: dati dell'organizzazione

Tipo: permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed one of: ['read:compliance_org_data', 'read:org_audit']

Causa: Una chiave senza read:compliance_org_data è stata usata per chiamare un endpoint di organizzazioni, ruoli, gruppi o impostazioni effettive. Esistono 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 includono 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; è necessaria la Compliance Access Key.

Scope ritirato: impostazioni dell'organizzazione

Tipo: permission_error

Missing required scopes. Got: ['read:compliance_org_settings'] Needed one of: ['read:compliance_org_data', 'read:org_audit']

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 include 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 di una 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, quindi elimina la vecchia chiave. Una chiave che include già read:compliance_org_data non è interessata dal ritiro.

Scope insufficiente: dati degli utenti

Tipo: permission_error

Missing required scopes. Got: ['read:compliance_activities'] Needed one of: ['read:compliance_user_data', 'read:org_audit']

Causa: Una chiave senza read:compliance_user_data è stata usata per chiamare un endpoint di chat, messaggi, file, progetti, sessioni, utenti dell'organizzazione o membri dei gruppi. Esistono 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 includono 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, sessioni, 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 effettivamente riguardare solo l'Activity Feed, indirizza invece la chiave Admin API a GET /v1/compliance/activities.

Scope insufficiente: eliminazione

Tipo: 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

Un 404 il cui messaggio nomina una risorsa o un tipo di risorsa significa che l'ID nel percorso non esiste o è già stato eliminato. Le eliminazioni tramite la Compliance API sono immediate e permanenti, quindi un 404 su un ID noto in precedenza di solito significa che il contenuto non esiste più: eliminato definitivamente tramite una chiamata di eliminazione della Compliance API, rimosso da una policy di conservazione oppure, per file e artifact, eliminato insieme alla relativa chat da un utente in claude.ai. Un 404 con il semplice messaggio Not found è diverso: la richiesta non è stata autenticata (o il percorso non esiste), e qualsiasi endpoint può restituirlo, inclusi gli endpoint di elenco; consulta Richiesta non autenticata. Gli endpoint delle sessioni aggiungono due casi. Sugli endpoint delle sessioni locali, un messaggio 404 distinto, Local sessions are not available., viene restituito a ogni chiamata (incluso l'elenco) finché gli endpoint non sono disponibili per la tua organizzazione padre; non dipende dall'ID della sessione e può essere temporaneo. Consulta Sessione locale non trovata. Sugli endpoint delle sessioni remote, una sessione ancora in fase di provisioning (status pari a pending) non ha ancora una trascrizione, quindi il suo endpoint dei messaggi restituisce 404 finché la sessione non si avvia. Consulta Sessione remota non trovata. Le stringhe dei tipi di attività citate in ciascuna Soluzione (ad esempio, claude_chat_created) sono valori che puoi passare al filtro activity_types[] dell'Activity Feed; consulta Interrogare le attività di conformità per tutti i valori supportati.

Richiesta non autenticata

Tipo: not_found_error

Not found

Causa: La richiesta non conteneva una credenziale accettata dalla Compliance API: non è stata inviata alcuna chiave API, oppure la chiave non è una Compliance Access Key (sk-ant-api01-...) né una chiave Admin API (sk-ant-admin01-...), ad esempio una chiave API di Claude (sk-ant-api03-...). Lo stato, il tipo e il messaggio sono gli stessi di un percorso inesistente e non dipendono dall'endpoint né da alcun ID di risorsa, quindi anche gli endpoint di elenco come GET /v1/compliance/activities restituiscono questo corpo. L'unica eccezione è GET /v1/compliance/organizations/{organization_id}/settings, che risponde a queste richieste con 401 authentication_error. Su ogni endpoint, una Compliance Access Key o una chiave Admin API che non supera l'autenticazione restituisce invece 401 Unauthorized.

Soluzione: Invia la chiave nell'intestazione x-api-key e controllane il prefisso: la Compliance API accetta solo chiavi sk-ant-api01-... e sk-ant-admin01-...; consulta Di quale chiave hai bisogno?. Se l'intestazione e la chiave sono corrette e un percorso restituisce ancora Not found mentre altri funzionano, verifica quel percorso rispetto al riferimento della Compliance API.

Chat non trovata

Tipo: not_found_error

Chat conversation not found: 'claude_chat_01H5CWunD7RpVJ5bHa8RCkja'

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 eliminate da un utente in claude.ai non restituiscono 404; rimangono leggibili, con deleted_at valorizzato, ma senza il contenuto dei messaggi.

Soluzione: Verifica l'ID della chat rispetto a un'attività claude_chat_created o claude_chat_viewed recente. Se l'attività è recente e la lettura continua a non riuscire, 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

Tipo: not_found_error

File not found: 0d3b8f72-6c1e-4a59-b2de-7f4c9a1e5b60

Causa: L'ID del file non esiste in un'organizzazione che la tua chiave può leggere, oppure il file è stato eliminato. L'eliminazione di una chat in claude.ai elimina anche i file allegati, anche se la chat stessa rimane elencata. Il messaggio identifica il file tramite il suo UUID sottostante anziché tramite l'ID claude_file_... inviato nella richiesta. Gli endpoint dei metadati, del contenuto e di eliminazione restituiscono questo corpo; si applica sia ai file allegati alle chat (claude_file_...) sia ai file dei progetti.

Soluzione: Effettua una riconciliazione con le attività claude_file_uploaded o claude_file_deleted recenti. I file eliminati insieme a una chat non hanno un'attività claude_file_deleted, quindi controlla anche l'attività claude_chat_deleted della chat. Se il file è stato eliminato, il binario non esiste più; i record delle attività rimangono nel feed per la finestra di conservazione di 6 anni.

File generato o artifact non trovato

Tipo: not_found_error

Generated file not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX'

Generated file content not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX'

Artifact version not found: 'claude_artifact_version_01KmNpQrSt3UvWxYz5AbCdEfG'

Causa: L'ID nel percorso non corrisponde a un file generato da uno strumento o a una versione di artifact leggibile tramite la Compliance API. L'endpoint dei metadati dei file generati restituisce il primo corpo, l'endpoint del contenuto restituisce il secondo ed entrambi gli endpoint degli artifact restituiscono il terzo. I file generati e gli artifact vengono eliminati insieme alla chat in cui sono stati creati, anche quando un utente elimina la chat in claude.ai.

Soluzione: Usa Ottenere i messaggi della chat per individuare la chat da cui proviene l'ID. Se il campo deleted_at della chat è valorizzato, oppure un'attività claude_chat_deleted nomina la chat, il contenuto non esiste più; rimuovi l'ID dalla tua coda. Altrimenti, verifica l'ID rispetto agli array generated_files e artifacts nei messaggi della chat.

Progetto non trovato

Tipo: not_found_error

No project is found with the provided id.

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

Causa: L'ID del progetto non esiste o è stato eliminato. Gli endpoint dei dettagli del progetto, degli allegati e dei collaboratori restituiscono il primo corpo; DELETE /v1/compliance/apps/projects/{project_id} restituisce il secondo.

Soluzione: Effettua una riconciliazione con le attività claude_project_created o claude_project_deleted recenti. 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

Tipo: not_found_error

No project document found with the provided id.

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

Causa: L'ID del documento del progetto non esiste o è stato eliminato. Gli endpoint di contenuto e metadati del documento restituiscono il primo corpo; DELETE /v1/compliance/apps/projects/documents/{document_id} restituisce il secondo. 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. Il record di attività mostra chi ha caricato il documento, quando e in quale progetto, ma non il suo nome.

Sessione locale non trovata

Tipo: not_found_error

Local session not found.

Causa: L'ID della sessione passato a GET /v1/compliance/apps/sessions/local/{session_id} o a GET /v1/compliance/apps/sessions/local/{session_id}/messages non corrisponde a una sessione locale leggibile tramite la Compliance API. Entrambi gli endpoint restituiscono questo unico messaggio, senza distinguere la causa, quando l'ID non è una sessione in un'organizzazione che la tua chiave può leggere (inclusi gli ID che appartengono a un'altra organizzazione padre), quando la sessione non è mai esistita, quando per la sessione è in vigore la conservazione zero dei dati, oppure quando tutta l'attività della sessione ha superato il periodo di conservazione applicabile all'organizzazione che l'ha eseguita. La risposta Local session not found. non ha una forma transitoria, perché le sessioni locali non hanno uno stato di provisioning (pending); confronta con Sessione remota non trovata, dove una sessione pending restituisce 404 finché non si avvia. Un ID di sessione che non è un identificatore clls_ ben formato restituisce invece 400 Bad Request.

Gli endpoint delle sessioni locali, incluso l'endpoint di elenco, restituiscono un messaggio 404 diverso, Local sessions are not available., quando gli endpoint stessi non sono disponibili per la tua organizzazione padre. Quella risposta non dipende dall'ID della sessione; nessuna chiave, scope o impostazione lato cliente la modifica, e può essere temporanea. Entrambe le risposte hanno il tipo not_found_error; è il testo del messaggio a distinguerle.

Soluzione: Verifica l'ID della sessione rispetto a GET /v1/compliance/apps/sessions/local; consulta Sessioni sui computer degli utenti. Se la sessione non compare più nell'elenco, il suo contenuto ha superato il periodo di conservazione (oppure la sessione non si trova più in un'organizzazione che la tua chiave può leggere) e la sua trascrizione non è recuperabile; rimuovi l'ID dalla tua coda. Se ogni chiamata, incluso l'elenco, restituisce Local sessions are not available., conserva gli ID delle sessioni in coda e riprova alla prossima esecuzione pianificata; se la risposta persiste, contatta il tuo referente Anthropic e includi l'intestazione di risposta request-id.

Sessione remota non trovata

Tipo: not_found_error

Remote session not found.

Causa: L'ID della sessione passato a GET /v1/compliance/apps/sessions/remote/{session_id}/messages non corrisponde a una trascrizione di sessione leggibile tramite la Compliance API. Ciò si verifica quando l'ID della sessione (cse_...) non esiste o la sessione è stata eliminata, quando la sessione appartiene a un'organizzazione che la tua chiave non può leggere, oppure quando lo status della sessione è ancora pending: una sessione in attesa non ha ancora una trascrizione, quindi l'endpoint dei messaggi restituisce 404 finché la sessione non si avvia. Un ID di sessione che non è un identificatore cse_ ben formato restituisce invece 400 Bad Request.

Soluzione: Verifica l'ID della sessione e il suo status rispetto a GET /v1/compliance/apps/sessions/remote; consulta Sessioni nel cloud. Se la sessione è pending, riprova dopo che ha lasciato quello stato. Se la sessione non compare più nell'elenco, è stata eliminata e la sua trascrizione non è recuperabile.

Organizzazione, ruolo o gruppo non trovato

Tipo: 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 relativo all'organizzazione nomina l'org_uuid; i messaggi relativi a ruoli e gruppi sono generici (Role not found., Group not found.). Ciò si verifica quando un ID nel percorso (org_uuid, role_id o group_id) non esiste o non appartiene più a una gerarchia 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 dalla gerarchia padre.

Soluzione: Verifica l'ID rispetto all'endpoint di elenco corrispondente ed effettua una riconciliazione con le attività recenti relative a organizzazioni, ruoli o gruppi nell'Activity Feed.

Impostazioni dell'organizzazione non disponibili

Tipo: 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 alla tua organizzazione 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 sicuramente 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 corpo ha il tipo invalid_request_error, usato anche dalle risposte 400, quindi distingui un conflitto tramite il codice di stato 409 anziché tramite error.type.

Il progetto ha chat collegate

Tipo: invalid_request_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 collegate.

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}, 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 (le Compliance Access Key e le chiavi Admin API di tutte le organizzazioni collegate) e tra tutti gli endpoint /v1/compliance/*; gli endpoint delle sessioni remote prevedono in aggiunta un secondo budget di richieste. Per un'organizzazione Claude Console autonoma, che non ha un'organizzazione padre, lo stesso budget si applica all'organizzazione stessa ed è condiviso tra le sue chiavi Admin API. Contatta il tuo referente Anthropic se la tua integrazione necessita di un limite più alto.

Un 429 fa eccezione: su una sessione molto grande, l'endpoint dei messaggi delle sessioni locali potrebbe restituire Server occupato nella lettura di trascrizioni di grandi dimensioni, che non è un "rate limit" (limite di velocità) né un limite sulla tua organizzazione. La relativa voce, alla fine di questa sezione, spiega come identificarlo e cosa fare.

Una volta che la tua chiave API è autenticata, le risposte della Compliance API riportano il budget condiviso tramite gli header di risposta standard del limite di velocità, in modo che il tuo client possa limitare le richieste in modo proattivo invece di attendere un 429:

• anthropic-ratelimit-requests-limit è il budget di richieste al minuto.
• 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 (o l'organizzazione Claude Console autonoma) ha inviato più di 600 richieste a /v1/compliance/* in una finestra di 1 minuto, considerando tutte le chiavi che ne condividono il budget, oppure ha esaurito il secondo budget di richieste degli endpoint delle sessioni remote (descritto più avanti in questa sezione).

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

Le richieste che non superano 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 priva dello scope richiesto dall'endpoint consuma un'unità di quota prima che venga restituito il 403.

Gli endpoint delle sessioni locali vengono conteggiati solo rispetto al limite condiviso. Gli endpoint delle sessioni remote prevedono inoltre un secondo budget di richieste, associato alla tua organizzazione padre come il limite condiviso, in aggiunta a quest'ultimo. Un 429 proveniente da quel budget include un header retry-after che vale sempre 1 (un'attesa minima, non l'effettivo momento di reimpostazione); eventuali header anthropic-ratelimit-* in quella risposta descrivono il limite condiviso anziché questo budget, quindi applica un backoff esponenziale se il 429 si ripete. Un solo tipo di 429 non proviene da alcun budget di richieste: Server occupato nella lettura di trascrizioni di grandi dimensioni, che viene restituito solo dall'endpoint dei messaggi delle sessioni locali.

Se interroghi l'Activity Feed a intervalli programmati, mantieni la frequenza aggregata delle richieste (su tutte le chiavi, le organizzazioni collegate e i worker concorrenti) al di sotto del limite condiviso. Monitora anthropic-ratelimit-requests-remaining per rallentare prima di raggiungerlo. Consulta Progetta la tua integrazione di conformità per scegliere tra il polling a finestre e l'acquisizione guidata dal cursore.

Server occupato nella lettura di trascrizioni di grandi dimensioni

Tipo: rate_limit_error

Codice di errore: transcript_read_server_busy, restituito in error.details.error_code

Too many large session transcripts are being read at once. This is not a limit on your organization. Retry this request after the number of seconds in the retry-after header.

Causa: GET /v1/compliance/apps/sessions/local/{session_id}/messages potrebbe restituire questo 429 per una pagina di una sessione molto grande. Solo questo endpoint restituisce questo errore, e può verificarsi con entrambi i valori di order. Non è un limite di velocità né un limite sulla tua organizzazione: non significa che hai superato il limite condiviso o qualsiasi altro budget di richieste. Questo errore condivide il codice di stato 429 e il tipo rate_limit_error con le risposte di limite di velocità, quindi identificalo tramite il suo codice di errore, non tramite il testo del messaggio, che potrebbe essere riformulato.

Soluzione: Attendi il numero di secondi indicato nell'header retry-after, quindi invia di nuovo la stessa richiesta, senza modifiche: mantieni lo stesso valore di page, oppure nessuno se la richiesta non ne aveva. Se il nuovo tentativo restituisce di nuovo questo errore, attendi e riprova allo stesso modo. Se l'header retry-after è assente, ricorri al backoff esponenziale (inizia da 1 secondo, raddoppiando fino a 60 secondi). Se questo errore continua a ripresentarsi tra un'esecuzione e l'altra, contatta il tuo referente Anthropic e includi l'header di risposta request-id.

500 Internal Server Error

Un 500 dalla Compliance API include un header di risposta x-should-retry: false quando l'errore è deterministico. L'SDK di Claude rispetta automaticamente questo header. Se usi una libreria HTTP generica che ripete automaticamente le richieste su ogni 5xx, disattiva i nuovi tentativi quando x-should-retry è false; ritentare 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, raddoppiando fino a 60 secondi). Lo stesso vale per le risposte 502, 503, 504 e 529. L'eccezione è un piccolo insieme di 503 delle sessioni locali, descritti di seguito, che dipendono dalle impostazioni o dalla chiave di crittografia di un'organizzazione anziché dal carico. Consulta Errori per la semantica dei nuovi tentativi valida per l'intera piattaforma.

Sessioni locali temporaneamente non disponibili

Tipo: overloaded_error

The local-sessions index is temporarily unavailable. Try again shortly.

Captured content is temporarily unavailable. Try again shortly.

The local-sessions index cannot currently evaluate retention overrides for this page. Try again later.

Causa: Gli endpoint delle sessioni locali restituiscono 503 con uno di questi corpi. Tutti e tre condividono il tipo overloaded_error. Questo è quindi uno dei pochi errori di questa pagina in cui, per distinguere le condizioni, ti serve il testo del messaggio e non error.type:

• Il corpo index is temporarily unavailable indica che gli elenchi delle sessioni sono brevemente non disponibili a causa del carico o di una condizione del backend. Si tratta di una condizione transitoria.
• Il corpo Captured content indica che al momento non è possibile restituire il contenuto della trascrizione di una sessione. Anche questa condizione è di solito transitoria. Nelle organizzazioni che usano chiavi di crittografia gestite dal cliente, l'endpoint dei messaggi restituisce questo corpo anche per ogni pagina con contenuto che la tua chiave gestita dal cliente non riesce a decrittografare. Può succedere, per esempio, perché hai disabilitato, revocato o distrutto la chiave, oppure perché la chiave non è raggiungibile. In quel caso l'errore persiste finché la chiave non può essere usata. Il testo del messaggio è lo stesso in entrambi i casi. L'unico segnale che la causa è la chiave è quindi il ripetersi dell'errore per quell'organizzazione. Una chiave inutilizzabile non viene mai segnalata come not_captured.
• Il corpo retention overrides indica che non è stato ancora possibile valutare un'impostazione di conservazione o di gestione dei dati che si applica a una o più sessioni nell'intervallo richiesto. Sugli endpoint di recupero e dei messaggi riporta for this session invece di for this page. Questa condizione non dipende dal carico, ma dai dati e dalle impostazioni dell'organizzazione che ha eseguito la sessione, e può persistere per un periodo prolungato.

Soluzione: Gestisci ciascun corpo come segue:

• Per i due corpi Try again shortly., riprova con "exponential backoff" (attesa esponenziale tra i tentativi). Non far avanzare il tuo cursore page, perché la richiesta non riuscita non ha restituito dati.
• Se il corpo Captured content continua a ripresentarsi sull'endpoint dei messaggi per un'organizzazione che usa una chiave gestita dal cliente, consideralo persistente. Interrompi la scansione delle trascrizioni di quell'organizzazione e controlla lo stato della chiave nel tuo servizio di gestione delle chiavi. Le trascrizioni nelle altre organizzazioni collegate e i metadati delle sessioni in tutte le organizzazioni non sono interessati. Se riprovi in un'esecuzione successiva, riavvia la scansione di ogni sessione senza page, perché i cursori di pagina dei messaggi scadono 24 ore dopo la prima pagina della scansione.
• Per il corpo Try again later., non tenere aperta una scansione in attesa che la condizione si risolva. Sull'endpoint di elenco, riprova più tardi riavviando senza il parametro page (un token di pagina dell'elenco più vecchio di 24 ore viene ancora accettato, ma viene rivalutato rispetto al limite di conservazione attuale, quindi una scansione sospesa può saltare delle sessioni), oppure restringi la finestra created_at finché la richiesta non va a buon fine, ed esporta separatamente l'intervallo saltato in un'esecuzione successiva. Sugli endpoint di recupero e dei messaggi, salta quell'ID di sessione, prosegui con il resto dell'esportazione e riprova la sessione in un'esecuzione successiva. I cursori di pagina dei messaggi scadono 24 ore dopo la prima pagina della scansione, quindi quando torni a quella sessione riavviane la scansione senza page.

Se una di queste condizioni si ripresenta in più esecuzioni, contatta il tuo referente Anthropic e includi l'header di risposta request-id. Nel caso della chiave gestita dal cliente, fallo solo se l'errore continua mentre quella chiave è utilizzabile.

Per gli incidenti che interessano l'intero servizio, consulta status.anthropic.com.

Passaggi successivi