Manejar 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 un formato de error consistente con el resto del formato de error 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 el problema a soporte.

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

Haz coincidir según error.type, no según 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 tipo forman 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 de 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 no válido

Tipo: 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 no válido

Tipo: 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 no válido

Tipo: 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. Siempre copia 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 (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 error 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 no válida

Tipo: 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 revisa 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 Obtener acceso a la Compliance API.

403 Forbidden

La clave en x-api-key es válida pero no tiene el scope que requiere el endpoint. El mensaje textual enumera los scopes que tiene la clave (Got:) y los scopes que requiere el endpoint (Needed:), para que puedas confirmar qué 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

Tipo: 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 se habilitara la Compliance API para la organización. Las claves creadas antes de la habilitación no tienen el scope; consulta Después de la habilitación: organizaciones de Claude Console.

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

Tipo: 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 o grupos. 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 insuficiente: datos de usuario

Tipo: 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 chat, archivo, proyecto, adjunto de proyecto, usuario 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 de 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 en 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

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

Tipo: 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 permanentemente mediante una llamada previa de la Compliance API o eliminado 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 temporal (soft-delete) en claude.ai no devuelven 404; siguen siendo legibles con deleted_at poblado.

Solución: Confirma el ID de chat contra una actividad reciente de claude_chat_created o claude_chat_viewed. Si la actividad es reciente y la lectura aún falla, el chat ha sido eliminado permanentemente (a través de esta API o por vencimiento 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

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

Causa: El ID de 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 de 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

Tipo: not_found_error

No project is found with the provided id.

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

Solución: Concilia contra actividades recientes de 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 en sí haya desaparecido.

Documento de proyecto no encontrado

Tipo: not_found_error

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

Causa: El ID de documento de 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

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 organización, rol y grupo 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 principal.

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.

409 Conflict

La solicitud está bien formada y autorizada pero entra en conflicto con el estado actual del recurso.

El proyecto tiene chats adjuntos

Tipo: 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 aún 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 endpoint de listado de chats 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 principal. El límite es un único presupuesto compartido entre todas las claves bajo la organización principal (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 regular proactivamente en lugar de esperar un 429:

• anthropic-ratelimit-requests-limit es el presupuesto de solicitudes por minuto de tu organización principal.
• 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 se restablece la ventana y se restaura el presupuesto completo.

Una respuesta 429 también incluye 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 principal 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 en la autenticación (una clave faltante o no reconocida, o una clave de API de Claude 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.

Si consultas periódicamente el Activity Feed según un cronograma, presupuesta tu tasa agregada de solicitudes (entre todas las claves, organizaciones vinculadas y workers concurrentes) por debajo del límite de la organización principal. 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.

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 manera 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 conocer la semántica de reintentos de toda la plataforma.

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

Tamaño máximo de respuesta excedido

Tipo: api_error

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

Causa: Un endpoint de listado sin paginación (notablemente GET /v1/compliance/organizations) habría devuelto más de su límite máximo de 1,000 registros.

Solución: El endpoint de organizaciones devuelve el árbol completo en una sola llamada, hasta 1,000 organizaciones vinculadas. Si tu árbol excede 1,000, contacta al soporte de Anthropic para obtener asistencia con listas de organizaciones más grandes. Si estabas consultando periódicamente este endpoint para rastrear cambios de membresía de organizaciones, el relistado periódico sigue siendo el enfoque más confiable una vez que se resuelva el límite; captura adiciones y eliminaciones independientemente de qué lado de la relación principal-secundaria las inició. El Activity Feed también expone eventos de membresía a través de los tipos de actividad org_deletion_requested, org_deleted_via_bulk, org_parent_join_proposal_created y org_join_proposal_decided, que puedes usar para activar un relistado inmediato en lugar de esperar al siguiente intervalo de sondeo.

Próximos pasos