Maneja errores de la Compliance API

Esta página enumera los mensajes de respuesta que devuelve cada endpoint documentado de la Compliance API, la causa y la solución.

La Compliance API devuelve errores en el formato de error estándar de Anthropic: un código de estado no 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": "authentication_error",
    "message": "The API key provided is invalid or has been revoked."
  }
}

Haz coincidir con error.type, no con la cadena del mensaje. Los mensajes son lo suficientemente estables como para copiarlos en runbooks, pero podrían reformularse con el tiempo; los valores de type son parte del contrato de la API.

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



400 Bad Request

La solicitud era sintácticamente válida pero contenía un parámetro que el servidor rechazó. Corrige el parámetro y reintenta.



Formato de marca de tiempo inválido

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 valor de created_at.* o updated_at.* (.gte, .gt, .lte, .lt) no pudo analizarse como datetime. El mensaje nombra el parámetro que falló y repite el valor que se envió.

Solución: Envía una marca de tiempo RFC 3339 completa que incluya hora y zona horaria, por ejemplo, 2024-03-01T00:00:00Z o 2024-03-01T00:00:00+00:00.



Límite inválido

Type: invalid_request_error

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

Causa: El parámetro de consulta limit estaba fuera del rango aceptado. El límite nombrado en el mensaje refleja el máximo para el endpoint específico que se llamó.

Solución: Envía un limit dentro del rango que acepta el endpoint. Cada endpoint de listado tiene su propio rango de limit; consulta las restricciones de parámetros en la página correspondiente de la referencia de la Compliance API.



ID de paginación inválido

Type: invalid_request_error

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

Causa: El cursor after_id o before_id no pudo decodificarse como un cursor opaco ni analizarse como un ID de actividad.

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 y proyectos (organizaciones, usuarios, roles, permisos de roles, grupos, miembros de grupos, proyectos y adjuntos de proyectos) paginan con un token page opaco en lugar de after_id y before_id. Aplica el mismo consejo: pasa el valor next_page de la respuesta anterior sin cambios, y detente cuando has_more sea false. Un token page mal formado devuelve el mismo 400 invalid_request_error que un after_id o before_id mal formado.



401 Unauthorized

El encabezado x-api-key faltaba o no coincidía con una clave conocida. Una clave válida con los scopes incorrectos devuelve 403 Forbidden en su lugar.



Clave de API inválida

Type: authentication_error

The API key provided is invalid or has been revoked.

Causa: La clave en x-api-key no existe, ha sido eliminada o ha sido deshabilitada. Un encabezado x-api-key faltante o vacío devuelve el mismo cuerpo, así que verifica tanto tu almacén de secretos como el estado de revocación de la clave.

Solución: Confirma el valor de la clave, verifica que no haya sido eliminada en claude.ai (Compliance Access Keys) o en Claude Console (claves de Admin API), y confirma que esté habilitada. Consulta Configura la Compliance API.



403 Forbidden

La clave en x-api-key es válida pero no tiene el scope que el endpoint requiere. El mensaje textual enumera los scopes que tiene la clave (Got:) y los scopes que requiere el endpoint (Needed:), para que puedas confirmar lo que tiene la clave sin volver a revisar Claude Console o claude.ai. Los scopes de las Compliance Access Keys son inmutables después de su creación, por lo que cada solución de scope insuficiente te indica crear una nueva clave en lugar de editar la existente.



Scope insuficiente: Activity Feed

Type: permission_error

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

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-...) antes de que la Compliance API se habilitara para la organización. Las claves creadas antes de la habilitación no tienen el scope; consulta Configura la Compliance API.

Solución: Los scopes de las Compliance Access Keys 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

Type: permission_error

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

Causa: Se usó una clave sin read:compliance_org_data para llamar a un endpoint de organizaciones, roles, grupos o configuraciones efectivas. 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

Type: permission_error

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

Causa: El scope read:compliance_org_settings fue retirado 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 las Compliance Access Keys 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

Type: permission_error

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

Causa: Se usó una clave sin read:compliance_user_data para llamar a un endpoint de chats, mensajes, archivos, proyectos, 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, 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

Type: 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 de chats, archivos o proyectos.

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



404 Not Found

El endpoint se resolvió pero el ID del recurso no existe o ya fue eliminado. Las eliminaciones de la Compliance API son inmediatas y permanentes, por lo que un 404 en un ID previamente conocido normalmente significa que el contenido fue eliminado de forma permanente mediante una llamada de eliminación de la Compliance API o removido por una política de retención. 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.



Chat no encontrado

Type: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

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 permanente mediante una llamada previa 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ó de forma reversible (soft-delete) en claude.ai no devuelven 404; permanecen legibles con deleted_at poblado.

Solución: Confirma el ID del 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 permanente (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

Type: not_found_error

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

Causa: El ID del archivo no existe o ha sido eliminado. Este error aplica tanto a archivos adjuntos a chats (claude_file_...) como a archivos de proyectos.

Solución: Concilia contra actividades recientes claude_file_uploaded o claude_file_deleted. Si el archivo fue eliminado, el binario ya no existe; el registro de actividad permanece en el feed durante la ventana de retención de 6 años.



Proyecto no encontrado

Type: not_found_error

No project is found with the provided id.

Causa: El ID del proyecto no existe o ha sido eliminado.

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



Documento de proyecto no encontrado

Type: not_found_error

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

Causa: El ID del documento del proyecto no existe o ha sido eliminado. Este error aplica a documentos de texto de proyectos (claude_proj_doc_...), no a archivos de proyectos.

Solución: Usa GET /v1/compliance/apps/projects/{project_id}/attachments para listar los adjuntos actuales. Si el documento falta, fue eliminado; recupéralo a través de un registro de actividad claude_project_document_uploaded si solo necesitas los metadatos.



Organización, rol o grupo no encontrado

Type: 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 listado correspondiente, y concilia contra actividades recientes de organización, rol o grupo en el Activity Feed.



Configuración de la organización no disponible

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 devuelve este 404 en tres casos que intencionalmente comparten 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 organización 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 se sabe 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 proyecto tiene chats adjuntos

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: Se llamó a DELETE /v1/compliance/apps/projects/{project_id} en 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 de 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 la organización padre (Compliance Access Keys y las claves de Admin API de todas las organizaciones vinculadas) y entre todos los endpoints /v1/compliance/*. Contacta a tu representante de Anthropic si tu integración necesita un límite más alto.

Una vez que tu clave de API se autentica, cada respuesta de la Compliance API incluye los encabezados de respuesta de 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 de tu organización padre.
• 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 incluye un encabezado retry-after con el número de segundos a 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 envió más de 600 solicitudes a /v1/compliance/* en una ventana de 1 minuto, entre todas sus claves y organizaciones vinculadas.

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 al backoff exponencial (comienza en 1 segundo, duplica hasta 60 segundos). No avances tu cursor de paginación en 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 API de Claude en lugar de una Compliance Access Key o una 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.

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



500 Internal Server Error

Un 500 de la Compliance API incluye un encabezado de respuesta x-should-retry: false cuando la falla es determinista. Los SDKs de Anthropic respetan este encabezado automáticamente. Si usas una biblioteca genérica de reintentos HTTP que reintenta en cada 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. Consulta Errores para la semántica de reintentos de toda la plataforma.

Para incidentes a nivel de servicio, consulta status.anthropic.com.



Próximos pasos