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 Anthropic standard: 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 richiesta al supporto.

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

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

Esegui il confronto 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. Gli endpoint delle sessioni locali hanno alcune eccezioni documentate in cui risposte che condividono un type si distinguono tramite il messaggio; ciascuna è segnalata dove si applica.

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

400 Bad Request

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

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 ha potuto essere interpretato come datetime. Il messaggio indica il parametro che ha fallito 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.

La lista delle sessioni locali (GET /v1/compliance/apps/sessions/local) restituisce anche un 400 invalid_request_error quando vengono forniti entrambi i limiti temporali e created_at.lt non è strettamente successivo a created_at.gte. Il corpo riporta:

created_at.lt must be strictly after created_at.gte.

Invia un created_at.lt successivo a created_at.gte, oppure ometti uno dei limiti.

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

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

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 loro parametri di troncamento allo stesso modo: tool_use_input_max_bytes e tool_result_max_bytes accettano ciascuno un numero di byte positivo oppure -1 (il massimo del server), quindi un valore come 0 restituisce lo stesso 400 invalid_request_error.

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 ha potuto essere 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, 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 il valore next_page della risposta precedente senza modificarlo 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.

I due endpoint paginati delle sessioni locali (la lista 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 sotto 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 diverso 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 del percorso (un passaggio 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 il parametro page; il nuovo percorso riflette il limite di conservazione in vigore al momento in cui inizia, quindi i messaggi che nel frattempo hanno superato il periodo di conservazione non vengono più restituiti (consulta Recuperare la trascrizione di una sessione locale).

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. Consulta Configurare la Compliance API.

403 Forbidden

La chiave in x-api-key è valida ma non possiede lo scope richiesto dall'endpoint. Il messaggio testuale 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. Un'organizzazione Claude Console autonoma (una 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

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. Esistono due percorsi comuni verso 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 possiedono lo scope; consulta 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. Consulta Di quale chiave hai bisogno? 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. Esistono due percorsi comuni verso 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; è necessaria 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 delle organizzazioni, 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, quindi elimina la vecchia chiave. Una chiave che già possiede 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, sessioni, utenti dell'organizzazione o membri dei gruppi. Esistono due percorsi comuni verso 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, 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 dovrebbe 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. Gli endpoint delle sessioni aggiungono due casi. Sugli endpoint delle sessioni locali, un messaggio 404 separato, Local sessions are not available., viene restituito a ogni chiamata (inclusa la lista) mentre 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 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 della 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 claude.ai non restituiscono 404; rimangono leggibili, con deleted_at popolato, ma senza il contenuto dei messaggi.

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 fallisce ancora, la chat è stata eliminata definitivamente (tramite questa API o per scadenza della policy di conservazione) oppure 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 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 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 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.

Sessione locale non trovata

Type: not_found_error

Local session not found.

Causa: L'ID della sessione passato a GET /v1/compliance/apps/sessions/local/{session_id} o 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 zero data retention, oppure quando tutta l'attività della sessione ha superato il periodo di conservazione che si applica 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 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 lista, restituiscono un messaggio 404 diverso, Local sessions are not available., mentre 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 type not_found_error; è il testo del messaggio a distinguerle.

Soluzione: Conferma l'ID della sessione rispetto a GET /v1/compliance/apps/sessions/local; consulta Sessioni sulle macchine degli utenti. Se la sessione non appare più nella lista, il suo contenuto ha superato la conservazione (oppure la sessione non è più, per altri motivi, in un'organizzazione che la tua chiave può leggere) e la sua trascrizione non è recuperabile; rimuovi l'ID dalla tua coda. Se ogni chiamata, inclusa la lista, restituisce Local sessions are not available., conserva gli ID di sessione in coda e ritenta alla prossima esecuzione pianificata; se la risposta persiste, contatta il tuo referente Anthropic e includi l'header di risposta request-id.

Sessione remota non trovata

Type: 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. Questo 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 pending 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: Conferma l'ID della sessione e il suo status rispetto a GET /v1/compliance/apps/sessions/remote; consulta Sessioni nel cloud. Se la sessione è pending, ritenta dopo che ha lasciato quello stato. Se la sessione non appare più nella lista, è stata eliminata e la sua trascrizione non è recuperabile.

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. Ruoli e gruppi possono essere eliminati e le organizzazioni possono essere scollegate dall'albero padre.

Soluzione: Verifica l'ID rispetto all'endpoint di lista 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 del 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 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 progetto ha chat collegate

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 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 ritenta 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 il padre (Compliance Access Keys e le chiavi Admin API di tutte le organizzazioni collegate) e tra tutti gli endpoint /v1/compliance/*; gli endpoint delle sessioni remote hanno 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.

Una volta che la tua chiave API si autentica, le risposte della Compliance API riportano il budget condiviso tramite gli header di risposta del limite di velocità standard ("rate limit", limite di velocità), così il tuo client può rallentare proattivamente 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 organizzazione Claude Console autonoma) ha inviato più di 600 richieste a /v1/compliance/* in una finestra di 1 minuto, tra tutte le chiavi che condividono il suo 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 ritenta. Se l'header è assente (ad esempio rimosso da un intermediario), ripiega sul backoff esponenziale (inizia da 1 secondo, raddoppia fino a 60 secondi). Non far 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 Claude API anziché una Compliance Access Key o una chiave Admin API) vengono rifiutate prima del rate limiter 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 contano solo rispetto al limite condiviso. Gli endpoint delle sessioni remote hanno anche un secondo budget di richieste, legato alla tua organizzazione padre come il limite condiviso, in aggiunta a esso. Un 429 da quel budget include un header retry-after che è sempre 1 (un'attesa minima, non il tempo effettivo di reimpostazione); eventuali header anthropic-ratelimit-* su quella risposta descrivono il limite condiviso anziché questo budget, quindi applica un backoff esponenziale se il 429 si ripete.

Se interroghi l'Activity Feed in modo pianificato, mantieni la tua frequenza di richieste aggregata (tra tutte le chiavi, le organizzazioni collegate e i worker concorrenti) al di sotto del limite condiviso. Osserva anthropic-ratelimit-requests-remaining per rallentare prima di raggiungerlo. Consulta Progettare la tua integrazione di compliance per scegliere tra polling a finestre e 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 Anthropic rispettano questo header automaticamente. Se usi una libreria HTTP di retry generica che ritenta su ogni 5xx, sopprimi i 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: ritenta con backoff esponenziale (inizia da 1 secondo, raddoppia 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 di retry a livello di piattaforma.

Sessioni locali temporaneamente non disponibili

Type: 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 type overloaded_error, quindi questo è uno dei pochi errori in questa pagina in cui ti serve il testo del messaggio, non error.type, per distinguere le condizioni:

• Il corpo index is temporarily unavailable significa che gli elenchi delle sessioni sono brevemente non disponibili a causa del carico o di una condizione del back-end. È transitorio.
• Il corpo Captured content significa che il contenuto della trascrizione di una sessione non può essere restituito in questo momento. Anche questo è di solito transitorio. Nelle organizzazioni che usano chiavi di crittografia gestite dal cliente, l'endpoint dei messaggi restituisce questo corpo anche per ogni pagina che contiene contenuti che la tua chiave non può decrittare, ad 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, quindi l'unico segnale che la causa è la chiave è che l'errore continua a ripetersi per quell'organizzazione. Una chiave inutilizzabile non viene mai segnalata come not_captured.
• Il corpo retention overrides significa che un'impostazione di conservazione o di gestione dei dati che si applica a una o più sessioni nell'intervallo richiesto non ha ancora potuto essere valutata. Sugli endpoint di recupero e dei messaggi riporta for this session invece di for this page. Dipende dai dati e dalle impostazioni dell'organizzazione che ha eseguito la sessione anziché dal carico, e può persistere per un periodo prolungato.

Soluzione: Gestisci ciascun corpo come segue:

• Per i due corpi Try again shortly., ritenta con backoff esponenziale e non far avanzare il cursore page, perché la richiesta fallita non ha restituito dati.
• Se il corpo Captured content continua a ripetersi sull'endpoint dei messaggi per un'organizzazione che usa una chiave gestita dal cliente, trattalo come persistente: interrompi il percorso 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 ovunque, non sono interessati. Se ritenti in un'esecuzione successiva, ricomincia il percorso di ogni sessione senza page, perché i cursori di pagina dei messaggi scadono 24 ore dopo la prima pagina del percorso.
• Per il corpo Try again later., non tenere aperto un percorso in attesa che si risolva. Sull'endpoint di lista, ritenta più tardi ricominciando senza il parametro page (un token di pagina della lista più vecchio di 24 ore è ancora accettato ma viene rivalutato rispetto al limite di conservazione corrente, quindi un percorso sospeso può saltare sessioni), oppure restringi la finestra created_at.gte e created_at.lt finché la richiesta non riesce ed esporta l'intervallo saltato separatamente in un'esecuzione successiva. Sugli endpoint di recupero e dei messaggi, salta quell'ID di sessione, continua con il resto dell'esportazione e ritenta la sessione in un'esecuzione successiva. I cursori di pagina dei messaggi scadono 24 ore dopo la prima pagina del percorso, quindi ricomincia il percorso di quella sessione senza page quando ci ritorni.

Se una di queste condizioni si ripete tra le esecuzioni, contatta il tuo referente Anthropic e includi l'header di risposta request-id. Per il caso della chiave gestita dal cliente, fallo solo se l'errore continua mentre la tua chiave è utilizzabile.

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

Passaggi successivi