Manejar errores de la Compliance API

Esta página enumera las respuestas de error comunes de la Compliance API por código de estado HTTP, con la causa y la solución para cada una.

La Compliance API devuelve errores en el formato de error estándar de Anthropic: un código de estado distinto de 2xx, un encabezado de respuesta request-id y un cuerpo JSON con un objeto error que contiene type y message. Incluye el valor del encabezado request-id cuando escales a soporte.

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

En esta página, las sesiones locales se ejecutan en las máquinas de los usuarios y las sesiones remotas se ejecutan en la nube; consulta Recuperar transcripciones de sesiones.

Basa la comparación en el código de estado HTTP y en error.type, no en la cadena del mensaje. Los mensajes son lo suficientemente estables como para copiarlos en runbooks, pero podrían redactarse de otra forma con el tiempo; los códigos de estado y los valores de tipo forman parte del contrato de la API. Algunas respuestas que comparten código de estado y tipo se distinguen por un código de error en error.details.error_code cuando la respuesta lo incluye y, en caso contrario, por su mensaje; cada una se señala donde corresponde.

La siguiente tabla te indica de un vistazo si debes reintentar. Cada sección que sigue muestra el cuerpo de error literal y la solución.

400 Bad Request

La solicitud era sintácticamente válida, pero el servidor rechazó un parámetro o la Compliance API no está habilitada para la organización. Corrige la causa indicada en el mensaje y vuelve a enviar la solicitud. Hay un 400 que es diferente: Página de transcripción demasiado grande, que el endpoint de mensajes de sesiones locales puede devolver para una página de una sesión muy grande incluso cuando todos los parámetros son válidos; su entrada indica qué hacer en lugar de reenviar.

Compliance API no habilitada

Tipo: invalid_request_error

Compliance API is not enabled for this organization

Causa: La clave es válida, pero la Compliance API no está habilitada para la organización u organización principal a la que pertenece la clave. Todos los endpoints devuelven esta respuesta hasta que se habilita la API, y de nuevo si un administrador desactiva la API.

Solución: Habilita la Compliance API siguiendo Configurar la Compliance API y luego vuelve a enviar la solicitud.

Parámetro de consulta desconocido

Tipo: invalid_request_error

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

Causa: La solicitud incluía un parámetro de consulta que el endpoint no define; la Compliance API rechaza los parámetros no reconocidos en lugar de ignorarlos. El mensaje nombra el parámetro y, para casos cercanos como la notación con corchetes en lugar de un punto o la falta del sufijo [], sugiere el nombre definido.

Solución: Usa los nombres de parámetros que se muestran en la página de referencia de la Compliance API del endpoint. Los filtros de rango usan notación de punto (por ejemplo, created_at.gte), los filtros de arreglo llevan el sufijo [] (por ejemplo, activity_types[]), y los parámetros de paginación son after_id, before_id o page, según el endpoint.

Valor de parámetro no válido

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: El valor de un parámetro de consulta no superó la validación. El mensaje comienza con el nombre del parámetro (seguido de la posición del elemento en el caso de un parámetro de arreglo) y luego indica la restricción que no se cumplió. Se muestran tres casos comunes: un limit por encima del máximo del endpoint (el número del mensaje es el máximo de ese endpoint), un valor de created_at.* o updated_at.* que no se puede interpretar como fecha o marca de tiempo, y un valor de activity_types[] que no es un tipo de actividad admitido.

Solución: Corrige el parámetro indicado en el mensaje. Cada endpoint de lista tiene su propio rango de limit; consulta las restricciones de parámetros en la página correspondiente de la referencia de la Compliance API. Envía las marcas de tiempo en formato RFC 3339 con un desfase UTC explícito, por ejemplo, 2024-03-01T00:00:00Z o 2024-03-01T00:00:00+00:00; la lista de sesiones locales rechaza una marca de tiempo sin desfase (created_at.gte: Input should have timezone info). Para conocer los valores admitidos de activity_types[], consulta Consultar actividades de cumplimiento.

La lista de sesiones locales (GET /v1/compliance/apps/sessions/local) también devuelve un 400 invalid_request_error cuando proporcionas un límite inferior (created_at.gte o created_at.gt) y un límite superior (created_at.lt o created_at.lte) y el límite superior no es posterior al inferior. Los límites iguales solo se permiten para created_at.gte con created_at.lte. El mensaje nombra los dos parámetros, por ejemplo:

created_at.lt must be strictly after created_at.gte.

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

Envía un límite superior posterior al límite inferior, u omite uno de los límites.

Los endpoints de transcripciones de sesiones (GET /v1/compliance/apps/sessions/local/{session_id}/messages y GET /v1/compliance/apps/sessions/remote/{session_id}/messages) validan sus parámetros de truncamiento de la misma manera: tool_use_input_max_bytes y tool_result_max_bytes aceptan cada uno un número positivo de bytes o -1 (el máximo del servidor), por lo que un valor como 0 devuelve el mismo 400 invalid_request_error.

Cursor de paginación no válido

Tipo: invalid_request_error

Invalid activity_id format: 'activity_invalid123'

Invalid pagination cursor for 'after_id'

Causa: No se pudo decodificar un "pagination cursor" (cursor de paginación). En el Activity Feed, un valor de after_id o before_id que no es ni un cursor emitido por la API ni un ID de actividad bien formado devuelve el primer cuerpo, que repite el valor enviado. En los endpoints de chats y de mensajes de chat, un valor de after_id o before_id que no se puede decodificar devuelve el segundo cuerpo, que nombra el parámetro.

Solución: Trata los cursores de paginación como cadenas opacas. Copia siempre el valor first_id o last_id devuelto por la página anterior; detente cuando has_more sea false. No construyas cursores a partir de IDs de objetos.

Los endpoints de directorio, proyectos y sesiones (organizaciones, usuarios, roles, permisos de roles, grupos, miembros de grupos, proyectos, adjuntos de proyectos, sesiones locales y remotas, y mensajes de sesiones) paginan con un token page opaco en lugar de after_id y before_id. Se aplica el mismo consejo: pasa sin cambios el valor de next_page de la respuesta anterior y detente cuando has_more sea false (o, en los endpoints de sesiones, que no devuelven has_more, cuando next_page sea null). Un token page mal formado devuelve el mismo 400 invalid_request_error que un after_id o before_id mal formado, con un mensaje específico del endpoint.

Los dos endpoints paginados de sesiones locales (el de lista y el de mensajes) devuelven el siguiente 400 invalid_request_error para cualquier valor de page que no puedan decodificar, por ejemplo, un token que fue truncado o alterado después de que lo almacenaste, o uno emitido por un endpoint diferente o bajo una organización padre diferente. En el endpoint de mensajes de sesiones locales (GET /v1/compliance/apps/sessions/local/{session_id}/messages), cada cursor page también está vinculado a la sesión y al order para los que fue emitido, por lo que un cursor emitido para una sesión u orden de clasificación diferente devuelve el mismo cuerpo:

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

Los cursores en el endpoint de mensajes también expiran 24 horas después de que comenzó el recorrido (una pasada por las páginas). Un cursor expirado devuelve:

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

Para el primer cuerpo, vuelve a enviar el valor next_page sin modificar de la respuesta anterior al endpoint y la sesión que lo emitieron. Para un cursor expirado, reinicia sin un parámetro page; el nuevo recorrido refleja el límite de retención vigente cuando comienza, por lo que los mensajes que salieron del período de retención en el ínterin ya no se devuelven (consulta Recuperar una transcripción de sesión local).

Página de transcripción demasiado grande

Tipo: invalid_request_error

Código de error: transcript_page_read_limit_exceeded, devuelto en 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 puede devolver este error para una página de una sesión muy grande. Solo este endpoint devuelve este error. Comparte el tipo invalid_request_error con los demás 400, así que identifícalo por su código de error, no por el texto del mensaje, que podría redactarse de otra forma.

Solución: No reintentes la solicitud. Si usaba order=desc, lee esa sesión empezando por lo más antiguo:

• Reinicia el recorrido de la sesión (una pasada por sus páginas; consulta Recuperar la transcripción de una sesión local) sin order (o con order=asc) y sin page, y sigue next_page hasta que sea null. Los mensajes que ya almacenaste de la lectura empezando por lo más reciente conservan el mismo id, así que elimina duplicados por id.
• Configura el tiempo de espera de solicitud de tu cliente en al menos 5 minutos para este recorrido.
• Reducir limit no es una forma fiable de evitar este error.

Si una solicitud empezando por lo más antiguo devuelve este error, tampoco la reintentes. Conserva las páginas que ya leíste, registra la sesión como incompleta, continúa con el resto de tu exportación y contacta a tu representante de Anthropic con el encabezado de respuesta request-id.

401 Unauthorized

La solicitud llevaba una Compliance Access Key (sk-ant-api01-...) o una clave de Admin API (sk-ant-admin01-...) que no se autentica. Una solicitud que no lleva ninguna clave, o que lleva una clave de otro tipo, devuelve en su lugar 404 Not Found en todos los endpoints excepto en el de configuración de la organización, y una clave válida con los alcances incorrectos devuelve 403 Forbidden.

Clave de API no válida, desactivada o caducada

Tipo: authentication_error

API key is invalid.

API key has been deactivated.

API key has expired.

Causa: API key is invalid. significa que el valor enviado no coincide con una clave utilizable, por ejemplo, porque se truncó o alteró al almacenarlo. API key has been deactivated. significa que la clave se ha deshabilitado o eliminado. API key has expired. significa que ha pasado la fecha de caducidad de una clave de Admin API; las Compliance Access Keys no se crean con una.

Solución: Para API key is invalid., compara el valor que envía tu cliente con el secreto que almacenaste al crear la clave; el secreto completo se muestra solo una vez, así que si tu copia almacenada es incorrecta, crea una clave nueva. Para API key has been deactivated., vuelve a habilitar la clave si solo se deshabilitó, en claude.ai > Organization settings > API para una Compliance Access Key o en la página Admin keys (platform.claude.com/settings/admin-keys) de Claude Console para una clave de Admin API; una clave eliminada no se puede restaurar. Para una clave eliminada o caducada, crea una clave nueva y actualiza tu integración para usarla, como se describe en Administrar y rotar claves.

403 Forbidden

La clave en x-api-key es válida, pero no lleva un alcance que el endpoint acepte. El mensaje literal enumera los alcances que lleva la clave (Got:) y los alcances que acepta el endpoint (Needed one of: en los endpoints de lectura, donde basta con cualquiera de los alcances enumerados, o Needed: en los endpoints de eliminación), para que puedas confirmar qué lleva la clave sin volver a revisar Claude Console o claude.ai. En los endpoints de lectura, la lista de alcances aceptados también incluye read:org_audit, un alcance de auditoría de solo lectura que cubre todos los endpoints de lectura de la Compliance API; consulta Elegir alcances para una clave de Claude Enterprise. Los alcances de una Compliance Access Key son inmutables después de su creación, por lo que cada solución por alcance insuficiente te indica que crees una clave nueva en lugar de editar la existente. Una organización independiente de Claude Console (una sin organización principal) no puede crear una Compliance Access Key, por lo que las soluciones que la requieren no se aplican a ella; solo puede consultar el Activity Feed.

Scope insuficiente: Activity Feed

Tipo: permission_error

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

Causa: Se usó una clave sin read:compliance_activities para llamar a GET /v1/compliance/activities. Hay dos caminos comunes hacia este error:

• Se creó una Compliance Access Key (sk-ant-api01-...) sin el scope read:compliance_activities.
• Se creó una clave de Admin API de Claude Console (sk-ant-admin01-...) mientras la Compliance API no estaba habilitada para la organización. Las claves creadas mientras la Compliance API no estaba habilitada no tienen el scope; consulta Configurar la Compliance API.

Solución: Los scopes de una Compliance Access Key son inmutables después de su creación. Crea una nueva clave que incluya read:compliance_activities, o usa una clave de Admin API de Claude Console. Consulta ¿Qué clave necesitas? para conocer las condiciones bajo las cuales una clave de Admin API tiene este scope.

Scope insuficiente: datos de la organización

Tipo: permission_error

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

Causa: Se usó una clave sin read:compliance_org_data para llamar a un endpoint de organizaciones, roles, grupos o configuración efectiva. Hay dos caminos comunes hacia este error:

• Se creó una Compliance Access Key (sk-ant-api01-...) sin el scope read:compliance_org_data.
• Se usó una clave de Admin API de Claude Console (sk-ant-admin01-...). Las claves de Admin API solo tienen read:compliance_activities y no pueden leer metadatos de la organización.

Solución: Crea una nueva Compliance Access Key con read:compliance_org_data seleccionado. Las claves de Admin API no pueden leer metadatos de la organización; se requiere la Compliance Access Key.

Scope retirado: configuración de la organización

Tipo: permission_error

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

Causa: El scope read:compliance_org_settings se retiró el 30 de junio de 2026. GET /v1/compliance/organizations/{organization_id}/settings ahora requiere read:compliance_org_data, el mismo scope que los demás endpoints de organización, y el scope retirado ya no autoriza nada. Una Compliance Access Key que solo tiene read:compliance_org_settings devuelve este error en cada llamada al endpoint de configuración, aunque la clave funcionara antes del retiro. El scope retirado ya no puede seleccionarse ni otorgarse al crear una clave.

Solución: Los scopes de una Compliance Access Key son inmutables después de su creación. Crea una nueva Compliance Access Key con read:compliance_org_data seleccionado, actualiza tu integración para usarla y luego elimina la clave antigua. Una clave que ya tiene read:compliance_org_data no se ve afectada por el retiro.

Scope insuficiente: datos de usuario

Tipo: permission_error

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

Causa: Se usó una clave sin read:compliance_user_data para llamar a un endpoint de chats, mensajes, archivos, proyectos, sesiones, usuarios de la organización o miembros de grupos. Hay dos caminos comunes hacia este error:

• Se creó una Compliance Access Key (sk-ant-api01-...) sin el scope read:compliance_user_data.
• Se usó una clave de Admin API de Claude Console (sk-ant-admin01-...). Las claves de Admin API solo tienen read:compliance_activities y no se les puede otorgar read:compliance_user_data, por lo que no pueden llamar a los endpoints de chats, archivos, proyectos, adjuntos de proyectos, sesiones, usuarios o miembros de grupos.

Solución: Usa una Compliance Access Key creada en claude.ai con read:compliance_user_data seleccionado. Si la solicitud realmente debería ser solo del Activity Feed, apunta la clave de Admin API a GET /v1/compliance/activities en su lugar.

Scope insuficiente: eliminación

Tipo: permission_error

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

Causa: Se usó una Compliance Access Key sin delete:compliance_user_data para llamar a un endpoint DELETE sobre chats, archivos o proyectos.

Solución: Crea una nueva Compliance Access Key con delete:compliance_user_data seleccionado. El scope de eliminación es independiente de read:compliance_user_data para que las claves de auditoría de solo lectura no puedan eliminar contenido.

404 Not Found

Un 404 cuyo mensaje nombra un recurso o un tipo de recurso significa que el ID de la ruta no existe o ya se ha eliminado. Las eliminaciones de la Compliance API son inmediatas y permanentes, por lo que un 404 en un ID conocido previamente suele significar que el contenido ha desaparecido: se eliminó de forma permanente mediante una llamada de eliminación de la Compliance API, lo eliminó una política de retención o, en el caso de archivos y artefactos, un usuario lo eliminó junto con su chat en claude.ai. Un 404 con el mensaje simple Not found es diferente: la solicitud no se autenticó (o la ruta no existe), y cualquier endpoint puede devolverlo, incluidos los endpoints de lista; consulta Solicitud no autenticada. Los endpoints de sesiones añaden dos casos. En los endpoints de sesiones locales, se devuelve un mensaje 404 distinto, Local sessions are not available., en cada llamada (incluida la de lista) mientras los endpoints no estén disponibles para tu organización principal; no depende del ID de sesión y puede ser temporal. Consulta Sesión local no encontrada. En los endpoints de sesiones remotas, una sesión que aún se está aprovisionando (status con valor pending) todavía no tiene transcripción, por lo que su endpoint de mensajes devuelve 404 hasta que la sesión se inicia. Consulta Sesión remota no encontrada. Las cadenas de tipo de actividad citadas en cada Solución (por ejemplo, claude_chat_created) son valores que puedes pasar al filtro activity_types[] del Activity Feed; consulta Consultar actividades de cumplimiento para ver todos los valores admitidos.

Solicitud no autenticada

Tipo: not_found_error

Not found

Causa: La solicitud no llevaba una credencial que la Compliance API acepte: no se envió ninguna clave de API, o la clave no es una Compliance Access Key (sk-ant-api01-...) ni una clave de Admin API (sk-ant-admin01-...), por ejemplo, una clave de API de Claude (sk-ant-api03-...). El estado, el tipo y el mensaje son los mismos que para una ruta que no existe y no dependen del endpoint ni de ningún ID de recurso, por lo que los endpoints de lista como GET /v1/compliance/activities también devuelven este cuerpo. La única excepción es GET /v1/compliance/organizations/{organization_id}/settings, que responde a estas solicitudes con 401 authentication_error. En todos los endpoints, una Compliance Access Key o una clave de Admin API que no se autentica devuelve en su lugar 401 Unauthorized.

Solución: Envía la clave en el encabezado x-api-key y comprueba su prefijo: la Compliance API solo acepta claves sk-ant-api01-... y sk-ant-admin01-...; consulta ¿Qué clave necesitas?. Si el encabezado y la clave son correctos y una ruta sigue devolviendo Not found mientras otras funcionan, compara esa ruta con la referencia de la Compliance API.

Chat no encontrado

Tipo: not_found_error

Chat conversation not found: 'claude_chat_01H5CWunD7RpVJ5bHa8RCkja'

Causa: El ID de chat en la ruta no coincide con un chat legible a través de la Compliance API. El chat podría haber sido eliminado de forma definitiva mediante una llamada anterior a la Compliance API o removido por la política de retención de tu organización, o podría pertenecer a una organización que la clave que realiza la llamada no puede leer. Los chats que un usuario eliminó en claude.ai no devuelven 404; siguen siendo legibles, con deleted_at poblado, pero sin el contenido de sus mensajes.

Solución: Confirma el ID de chat contra una actividad reciente claude_chat_created o claude_chat_viewed. Si la actividad es reciente y la lectura sigue fallando, el chat ha sido eliminado de forma definitiva (a través de esta API o por expiración de la política de retención) o pertenece a una organización fuera del alcance de tu clave.

Archivo no encontrado

Tipo: not_found_error

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

Causa: El ID de archivo no existe en una organización que tu clave pueda leer, o el archivo se ha eliminado. Eliminar un chat en claude.ai también elimina los archivos adjuntos a él, aunque el chat en sí siga apareciendo en la lista. El mensaje identifica el archivo por su UUID subyacente en lugar de por el ID claude_file_... enviado en la solicitud. Los endpoints de metadatos, contenido y eliminación devuelven este cuerpo; se aplica tanto a los archivos adjuntos a chats (claude_file_...) como a los archivos de proyectos.

Solución: Concilia con las actividades recientes claude_file_uploaded o claude_file_deleted. Los archivos eliminados junto con un chat no tienen una actividad claude_file_deleted, así que comprueba también la actividad claude_chat_deleted del chat. Si el archivo se eliminó, el binario ha desaparecido; los registros de actividad permanecen en el feed durante el período de retención de 6 años.

Archivo generado o artefacto no encontrado

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: El ID de la ruta no coincide con un archivo generado por herramientas ni con una versión de artefacto legible a través de la Compliance API. El endpoint de metadatos de archivos generados devuelve el primer cuerpo, el endpoint de contenido devuelve el segundo y ambos endpoints de artefactos devuelven el tercero. Los archivos generados y los artefactos se eliminan junto con el chat en el que se crearon, incluso cuando un usuario elimina el chat en claude.ai.

Solución: Usa Obtener mensajes de chat para buscar el chat del que proviene el ID. Si el deleted_at del chat está completado, o una actividad claude_chat_deleted nombra el chat, el contenido ha desaparecido; quita el ID de tu cola. De lo contrario, confirma el ID con los arreglos generated_files y artifacts de los mensajes del chat.

Proyecto no encontrado

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: El ID de proyecto no existe o se ha eliminado. Los endpoints de detalle, adjuntos y colaboradores del proyecto devuelven el primer cuerpo; DELETE /v1/compliance/apps/projects/{project_id} devuelve el segundo.

Solución: Concilia contra actividades recientes claude_project_created o claude_project_deleted. El Activity Feed sigue exponiendo los eventos del ciclo de vida del proyecto incluso después de que el proyecto en sí haya desaparecido.

Documento de proyecto no encontrado

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: El ID del documento de proyecto no existe o se ha eliminado. Los endpoints de contenido y metadatos del documento devuelven el primer cuerpo; DELETE /v1/compliance/apps/projects/documents/{document_id} devuelve el segundo. Este error se aplica a los documentos de texto de proyectos (claude_proj_doc_...), no a los archivos de proyectos.

Solución: Usa GET /v1/compliance/apps/projects/{project_id}/attachments para listar los adjuntos actuales. Si falta el documento, se eliminó; recupéralo mediante un registro de actividad claude_project_document_uploaded si solo necesitas los metadatos. El registro de actividad muestra quién subió el documento, cuándo y a qué proyecto, pero no su nombre.

Sesión local no encontrada

Tipo: not_found_error

Local session not found.

Causa: El ID de sesión pasado a GET /v1/compliance/apps/sessions/local/{session_id} o GET /v1/compliance/apps/sessions/local/{session_id}/messages no coincide con una sesión local legible a través de la Compliance API. Ambos endpoints devuelven este único mensaje, sin distinguir la causa, cuando el ID no es una sesión en una organización que tu clave puede leer (incluidos IDs que pertenecen a otra organización padre), cuando la sesión nunca existió, cuando la retención cero de datos está vigente para la sesión, o cuando toda la actividad de la sesión ha superado el período de retención que aplica a la organización que la ejecutó. La respuesta Local session not found. no tiene forma transitoria, porque las sesiones locales no tienen estado de aprovisionamiento (pending); compara con Sesión remota no encontrada, donde una sesión pending devuelve 404 hasta que se inicia. Un ID de sesión que no es un identificador clls_ bien formado devuelve 400 Bad Request en su lugar.

Los endpoints de sesiones locales, incluido el endpoint de lista, devuelven un mensaje 404 diferente, Local sessions are not available., mientras los propios endpoints no están disponibles para tu organización padre. Esa respuesta no depende del ID de sesión; ninguna clave, scope o configuración del lado del cliente la cambia, y puede ser temporal. Ambas respuestas tienen el type not_found_error; el texto del mensaje es lo que las distingue.

Solución: Confirma el ID de sesión contra GET /v1/compliance/apps/sessions/local; consulta Sesiones en las máquinas de los usuarios. Si la sesión ya no aparece en la lista, su contenido ha superado la retención (o la sesión ya no está, por otro motivo, en una organización que tu clave puede leer) y su transcripción no es recuperable; quita el ID de tu cola. Si cada llamada, incluida la de lista, devuelve Local sessions are not available., conserva tus IDs de sesión en cola y reintenta en tu próxima ejecución programada; si la respuesta persiste, contacta a tu representante de Anthropic e incluye el encabezado de respuesta request-id.

Sesión remota no encontrada

Tipo: not_found_error

Remote session not found.

Causa: El ID de sesión pasado a GET /v1/compliance/apps/sessions/remote/{session_id}/messages no coincide con una transcripción de sesión legible a través de la Compliance API. Esto ocurre cuando el ID de sesión (cse_...) no existe o la sesión ha sido eliminada, cuando la sesión pertenece a una organización que tu clave no puede leer, o cuando el status de la sesión aún es pending: una sesión pendiente todavía no tiene transcripción, por lo que el endpoint de mensajes devuelve 404 hasta que la sesión se inicia. Un ID de sesión que no es un identificador cse_ bien formado devuelve 400 Bad Request en su lugar.

Solución: Confirma el ID de sesión y su status contra GET /v1/compliance/apps/sessions/remote; consulta Sesiones en la nube. Si la sesión está pending, reintenta después de que salga de ese estado. Si la sesión ya no aparece en la lista, ha sido eliminada y su transcripción no es recuperable.

Organización, rol o grupo no encontrado

Tipo: not_found_error

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

Los endpoints de organizaciones, roles y grupos devuelven un 404 not_found_error en el formato de error estándar. El mensaje de organización nombra el org_uuid; los mensajes de rol y grupo son genéricos (Role not found., Group not found.). Esto ocurre cuando un ID de ruta (org_uuid, role_id o group_id) no existe o ya no pertenece a un árbol que la clave que realiza la llamada puede leer.

Causa: El ID en la ruta no coincide con un registro legible a través de la Compliance API. Los roles y grupos pueden eliminarse, y las organizaciones pueden desvincularse del árbol padre.

Solución: Verifica el ID contra el endpoint de lista correspondiente, y concilia contra actividades recientes de organización, rol o grupo en el Activity Feed.

Configuración de la organización no disponible

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 devuelve este 404 en tres casos que comparten intencionalmente el mismo cuerpo para que la respuesta no revele si una organización existe: el organization_id no es una de las organizaciones vinculadas de tu padre, el valor no es un UUID válido, o el endpoint de configuración aún no está habilitado para tu organización padre.

Solución: Verifica el ID contra Listar organizaciones. Si un ID de organización que sabes que es correcto sigue devolviendo 404, el endpoint de configuración aún no está habilitado para tu organización padre; contacta a tu representante de Anthropic.

409 Conflict

La solicitud está bien formada y autorizada, pero entra en conflicto con el estado actual del recurso. El cuerpo lleva el tipo invalid_request_error, que también usan las respuestas 400, así que distingue un conflicto por el código de estado 409 y no por error.type.

El proyecto tiene chats adjuntos

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: Se llamó a DELETE /v1/compliance/apps/projects/{project_id} sobre un proyecto que todavía tiene chats adjuntos.

Solución: Lista los chats del proyecto con GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} (el filtro project_ids[] requiere al menos un valor user_ids[]; enumera los IDs a través de Listar usuarios de la organización), elimina cada uno con DELETE /v1/compliance/apps/chats/{claude_chat_id}, y luego reintenta la eliminación del proyecto.

429 Too Many Requests

Las solicitudes a la Compliance API están limitadas a 600 solicitudes por minuto por organización padre. El límite es un único presupuesto compartido entre todas las claves bajo el padre (Compliance Access Keys y las claves de Admin API de todas las organizaciones vinculadas) y entre todos los endpoints /v1/compliance/*; los endpoints de sesiones remotas tienen además un segundo presupuesto de solicitudes. Para una organización independiente de Claude Console, que no tiene organización padre, el mismo presupuesto aplica a la propia organización y se comparte entre sus claves de Admin API. Contacta a tu representante de Anthropic si tu integración necesita un límite más alto.

Hay un 429 que es diferente: en una sesión muy grande, el endpoint de mensajes de sesiones locales podría devolver Servidor ocupado leyendo transcripciones grandes, que no es un "rate limit" (límite de velocidad) ni un límite sobre tu organización. Su entrada, al final de esta sección, explica cómo identificarlo y qué hacer.

Una vez que tu clave de API se autentica, las respuestas de la Compliance API informan el presupuesto compartido a través de los encabezados de respuesta de "rate limit" (límite de velocidad) estándar para que tu cliente pueda regularse proactivamente en lugar de esperar un 429:

• anthropic-ratelimit-requests-limit es el presupuesto de solicitudes por minuto.
• anthropic-ratelimit-requests-remaining es el presupuesto restante en la ventana actual.
• anthropic-ratelimit-requests-reset es la marca de tiempo RFC 3339 en la que la ventana se reinicia y se restaura el presupuesto completo.

Una respuesta 429 también tiene un encabezado retry-after con el número de segundos que debes esperar antes de enviar la siguiente solicitud. Este valor podría incluir un pequeño margen de seguridad más allá de anthropic-ratelimit-requests-reset; respeta 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: Tu organización padre (u organización independiente de Claude Console) envió más de 600 solicitudes a /v1/compliance/* en una ventana de 1 minuto, entre todas las claves que comparten su presupuesto, o agotó el segundo presupuesto de solicitudes de los endpoints de sesiones remotas (descrito más adelante en esta sección).

Solución: Espera el número de segundos indicado en el encabezado retry-after, luego reintenta. Si el encabezado está ausente (por ejemplo, eliminado por un intermediario), recurre a backoff exponencial (comienza en 1 segundo, duplica hasta 60 segundos). No avances tu cursor de paginación ante un 429: la solicitud fallida no devolvió datos, por lo que el cursor de la última página exitosa sigue siendo correcto.

Las solicitudes que fallan la autenticación (una clave faltante o no reconocida, o una clave de la Claude API en lugar de una Compliance Access Key o clave de Admin API) se rechazan antes del limitador de velocidad y no consumen cuota. Una clave válida que carece del scope requerido por el endpoint consume una unidad de cuota antes de que se devuelva el 403.

Los endpoints de sesiones locales cuentan solo contra el límite compartido. Los endpoints de sesiones remotas tienen además un segundo presupuesto de solicitudes, asociado a tu organización principal igual que el límite compartido, que se suma a este. Un 429 de ese presupuesto incluye un encabezado retry-after que siempre es 1 (una espera mínima, no el tiempo real de restablecimiento); cualquier encabezado anthropic-ratelimit-* en esa respuesta describe el límite compartido y no este presupuesto, así que aplica retroceso exponencial si el 429 se repite. Hay un 429 que no proviene de ningún presupuesto de solicitudes: Servidor ocupado leyendo transcripciones grandes, que solo devuelve el endpoint de mensajes de sesiones locales.

Si consultas el Activity Feed de forma programada, presupuesta tu tasa agregada de solicitudes (entre todas las claves, organizaciones vinculadas y workers concurrentes) por debajo del límite compartido. Observa anthropic-ratelimit-requests-remaining para reducir la velocidad antes de alcanzarlo. Consulta Diseña tu integración de cumplimiento para elegir entre sondeo por ventanas e ingesta basada en cursores.

Servidor ocupado leyendo transcripciones grandes

Tipo: rate_limit_error

Código de error: transcript_read_server_busy, devuelto en 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 podría devolver este 429 para una página de una sesión muy grande. Solo este endpoint devuelve este error, y podría ocurrir con cualquiera de los valores de order. No es un límite de velocidad ni un límite sobre tu organización: no significa que hayas superado el límite compartido ni ningún otro presupuesto de solicitudes. Este error comparte el código de estado 429 y el tipo rate_limit_error con las respuestas de límite de velocidad, así que identifícalo por su código de error, no por el texto del mensaje, que podría cambiar de redacción.

Solución: Espera el número de segundos indicado en el encabezado retry-after y luego envía la misma solicitud de nuevo, sin cambios: conserva el mismo valor de page, o ninguno si la solicitud no tenía. Si el reintento vuelve a devolver este error, espera y reintenta de la misma manera. Si el encabezado retry-after no está presente, recurre al retroceso exponencial (comienza con 1 segundo y duplica hasta 60 segundos). Si este error sigue repitiéndose entre ejecuciones, contacta a tu representante de Anthropic e incluye el encabezado de respuesta request-id.

500 Internal Server Error

Un 500 de la Compliance API incluye un encabezado de respuesta x-should-retry: false cuando el fallo es determinista. El SDK de Claude respeta este encabezado automáticamente. Si usas una biblioteca HTTP genérica de reintentos que reintenta ante cualquier 5xx, suprime los reintentos cuando x-should-retry sea false; reintentar este error falla de forma idéntica en cada intento.

Un 500 sin el encabezado x-should-retry: false es transitorio: reintenta con backoff exponencial (comienza en 1 segundo, duplica hasta 60 segundos). Lo mismo aplica a las respuestas 502, 503, 504 y 529. La excepción es un pequeño conjunto de 503 de sesiones locales, descritos a continuación, que dependen de la configuración o la clave de cifrado de una organización y no de la carga. Consulta Errores para conocer la semántica de reintentos de toda la plataforma.

Sesiones locales temporalmente no disponibles

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: Los endpoints de sesiones locales devuelven 503 con uno de estos cuerpos. Los tres comparten el type overloaded_error, por lo que este es uno de los pocos errores de esta página en los que necesitas el texto del mensaje, no error.type, para distinguir las condiciones:

• El cuerpo index is temporarily unavailable significa que los listados de sesiones no están disponibles brevemente debido a la carga o a una condición del backend. Esto es transitorio.
• El cuerpo Captured content significa que el contenido de la transcripción de una sesión no se puede devolver en este momento. Esto también suele ser transitorio. En las organizaciones que usan claves de cifrado administradas por el cliente, el endpoint de mensajes también devuelve este cuerpo para cada página que contenga contenido que tu clave administrada por el cliente no puede descifrar, por ejemplo, porque deshabilitaste, revocaste o destruiste la clave, o porque no se puede acceder a la clave. En ese caso, el error persiste mientras la clave no se pueda usar. El texto del mensaje es el mismo en ambos casos, por lo que la única señal de que la clave es la causa es que el error sigue repitiéndose para esa organización. Una clave inutilizable nunca se informa como not_captured.
• El cuerpo retention overrides significa que aún no se pudo evaluar una configuración de retención o de manejo de datos que se aplica a una o más sesiones del rango solicitado. En los endpoints de recuperación y de mensajes dice for this session en lugar de for this page. Depende de los datos y la configuración de la organización que ejecutó la sesión, no de la carga, y puede persistir durante un período prolongado.

Solución: Maneja cada cuerpo de la siguiente manera:

• Para los dos cuerpos Try again shortly., reintenta con backoff exponencial y no avances tu cursor page, porque la solicitud fallida no devolvió datos.
• Si el cuerpo Captured content sigue repitiéndose en el endpoint de mensajes para una organización que usa una clave administrada por el cliente, trátalo como persistente: deja de recorrer las transcripciones de esa organización y revisa el estado de la clave en tu servicio de administración de claves. Las transcripciones en otras organizaciones vinculadas, y los metadatos de sesiones en todas partes, no se ven afectados. Si reintentas en una ejecución posterior, reinicia el recorrido de cada sesión sin page, porque los cursores de página de mensajes expiran 24 horas después de la primera página del recorrido.
• Para el cuerpo Try again later., no mantengas un recorrido abierto esperando a que se resuelva. En el endpoint de lista, reintenta más tarde reiniciando sin el parámetro page (un token de página de lista con más de 24 horas de antigüedad aún se acepta pero se reevalúa contra el límite de retención actual, por lo que un recorrido en pausa puede omitir sesiones), o reduce la ventana de created_at hasta que la solicitud tenga éxito y exporta el rango omitido por separado en una ejecución posterior. En los endpoints de recuperación y de mensajes, omite ese ID de sesión, continúa con el resto de tu exportación y reintenta la sesión en una ejecución posterior. Los cursores de página de mensajes expiran 24 horas después de la primera página del recorrido, así que reinicia el recorrido de esa sesión sin page cuando vuelvas a ella.

Si alguna de estas condiciones se repite entre ejecuciones, comunícate con tu representante de Anthropic e incluye el encabezado de respuesta request-id. En el caso de la clave administrada por el cliente, hazlo solo si el error continúa mientras esa clave se puede usar.

Para incidentes que afectan a todo el servicio, consulta status.anthropic.com.

Próximos pasos