Lidar com erros da Compliance API

Esta página lista as mensagens de resposta que cada endpoint documentado da Compliance API retorna, a causa e a correção.

A Compliance API retorna erros em um formato de erro consistente com o restante do formato de erro da Anthropic: um código de status diferente de 2xx, um cabeçalho de resposta request-id e um corpo JSON com um objeto error contendo type e message. Inclua o valor do cabeçalho request-id ao escalar para o suporte.

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

Faça a correspondência com base em error.type, não na string da mensagem. As mensagens são estáveis o suficiente para serem copiadas em runbooks, mas podem ser reformuladas ao longo do tempo; os valores de type fazem parte do contrato da API.

A tabela a seguir informa rapidamente se você deve tentar novamente. Cada seção subsequente mostra o corpo de erro literal e a correção.

400 Bad Request

A requisição era sintaticamente válida, mas continha um parâmetro que o servidor rejeitou. Corrija o parâmetro e tente novamente.

Formato de timestamp 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: Um valor created_at.* ou updated_at.* (.gte, .gt, .lte, .lt) não pôde ser interpretado como um datetime. A mensagem nomeia o parâmetro que falhou e ecoa o valor que foi enviado.

Correção: Envie um timestamp RFC 3339 completo, incluindo hora e fuso horário, por exemplo, 2024-03-01T00:00:00Z ou 2024-03-01T00:00:00+00:00.

Limite inválido

Type: invalid_request_error

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

Causa: O parâmetro de consulta limit estava fora do intervalo aceito. O limite nomeado na mensagem reflete o máximo para o endpoint específico que foi chamado.

Correção: Envie um limit dentro do intervalo que o endpoint aceita. Cada endpoint de listagem tem seu próprio intervalo de limit; consulte as restrições de parâmetros na página correspondente da referência da Compliance API.

ID de paginação inválido

Type: invalid_request_error

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

Causa: O cursor after_id ou before_id não pôde ser decodificado como um cursor opaco ou interpretado como um ID de atividade.

Correção: Trate cursores de paginação como strings opacas. Sempre copie o valor first_id ou last_id retornado pela página anterior; pare quando has_more for false. Não construa cursores a partir de IDs de objetos.

Os endpoints de diretório e projeto (usuários, funções, permissões de função, grupos, membros de grupo, projetos e anexos de projeto) paginam com um token page opaco em vez de after_id e before_id. O mesmo conselho se aplica: passe o valor next_page da resposta anterior sem alterações e pare quando has_more for false. Um token page malformado retorna o mesmo 400 invalid_request_error que um after_id ou before_id malformado.

401 Unauthorized

O cabeçalho x-api-key estava ausente ou não correspondia a uma chave conhecida. Uma chave válida com os escopos errados retorna 403 Forbidden em vez disso.

Chave de API inválida

Type: authentication_error

The API key provided is invalid or has been revoked.

Causa: A chave em x-api-key não existe, foi excluída ou foi desativada. Um cabeçalho x-api-key ausente ou vazio retorna o mesmo corpo, então verifique tanto seu armazenamento de segredos quanto o status de revogação da chave.

Correção: Confirme o valor da chave, verifique se ela não foi excluída no claude.ai (Compliance Access Keys) ou no Claude Console (chaves da Admin API) e confirme que está ativada. Consulte Obter acesso à Compliance API.

403 Forbidden

A chave em x-api-key é válida, mas não possui o escopo que o endpoint exige. A mensagem literal lista os escopos que a chave possui (Got:) e os escopos que o endpoint exige (Needed:), para que você possa confirmar o que a chave possui sem verificar novamente o Claude Console ou o claude.ai. Os escopos da Compliance Access Key são imutáveis após a criação, então cada correção de escopo insuficiente orienta você a criar uma nova chave em vez de editar a existente.

Escopo insuficiente: Activity Feed

Type: permission_error

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

Causa: Uma chave sem read:compliance_activities foi usada para chamar GET /v1/compliance/activities. Há dois caminhos comuns para esse erro:

• Uma Compliance Access Key (sk-ant-api01-...) foi criada sem o escopo read:compliance_activities.
• Uma chave da Admin API do Claude Console (sk-ant-admin01-...) foi criada antes de a Compliance API ser habilitada para a organização. Chaves criadas antes da habilitação não possuem o escopo; consulte Após a habilitação: organizações do Claude Console.

Correção: Os escopos da Compliance Access Key são imutáveis após a criação. Crie uma nova chave que inclua read:compliance_activities ou use uma chave da Admin API do Claude Console. Consulte Qual chave você precisa? para as condições sob as quais uma chave da Admin API possui esse escopo.

Escopo insuficiente: dados da organização

Type: permission_error

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

Causa: Uma chave sem read:compliance_org_data foi usada para chamar um endpoint de organizações, funções ou grupos. Há dois caminhos comuns para esse erro:

• Uma Compliance Access Key (sk-ant-api01-...) foi criada sem o escopo read:compliance_org_data.
• Uma chave da Admin API do Claude Console (sk-ant-admin01-...) foi usada. Chaves da Admin API possuem apenas read:compliance_activities e não podem ler metadados da organização.

Correção: Crie uma nova Compliance Access Key com read:compliance_org_data selecionado. Chaves da Admin API não podem ler metadados da organização; a Compliance Access Key é obrigatória.

Escopo insuficiente: dados do usuário

Type: permission_error

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

Causa: Uma chave sem read:compliance_user_data foi usada para chamar um endpoint de chats, mensagens, arquivos, projetos, usuários da organização ou membros de grupo. Há dois caminhos comuns para esse erro:

• Uma Compliance Access Key (sk-ant-api01-...) foi criada sem o escopo read:compliance_user_data.
• Uma chave da Admin API do Claude Console (sk-ant-admin01-...) foi usada. Chaves da Admin API possuem apenas read:compliance_activities e não podem receber read:compliance_user_data, portanto não podem chamar os endpoints de chat, arquivo, projeto, anexo de projeto, usuário ou membros de grupo.

Correção: Use uma Compliance Access Key criada no claude.ai com read:compliance_user_data selecionado. Se a requisição realmente deveria ser apenas do Activity Feed, aponte a chave da Admin API para GET /v1/compliance/activities em vez disso.

Escopo insuficiente: exclusão

Type: permission_error

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

Causa: Uma Compliance Access Key sem delete:compliance_user_data foi usada para chamar um endpoint DELETE em chats, arquivos ou projetos.

Correção: Crie uma nova Compliance Access Key com delete:compliance_user_data selecionado. O escopo de exclusão é separado de read:compliance_user_data para que chaves de auditoria somente leitura não possam excluir conteúdo.

404 Not Found

O endpoint foi resolvido, mas o ID do recurso não existe ou já foi excluído. As exclusões da Compliance API são imediatas e permanentes, então um 404 em um ID previamente conhecido geralmente significa que o conteúdo foi excluído permanentemente por meio de uma chamada de exclusão da Compliance API ou removido por uma política de retenção. As strings de tipo de atividade citadas em cada Correção (por exemplo, claude_chat_created) são valores que você pode passar para o filtro activity_types[] do Activity Feed; consulte Consultar atividades de conformidade para todos os valores suportados.

Chat não encontrado

Type: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

Causa: O ID do chat no caminho não corresponde a um chat legível por meio da Compliance API. O chat pode ter sido excluído permanentemente por meio de uma chamada anterior da Compliance API ou removido pela política de retenção da sua organização, ou pode pertencer a uma organização que a chave chamadora não pode ler. Chats que um usuário excluiu de forma reversível no claude.ai não retornam 404; eles permanecem legíveis com deleted_at preenchido.

Correção: Confirme o ID do chat em relação a uma atividade recente claude_chat_created ou claude_chat_viewed. Se a atividade for recente e a leitura ainda falhar, o chat foi excluído permanentemente (por meio desta API ou por expiração da política de retenção) ou pertence a uma organização fora do escopo da sua chave.

Arquivo não encontrado

Type: not_found_error

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

Causa: O ID do arquivo não existe ou foi excluído. Esse erro se aplica tanto a arquivos anexados a chats (claude_file_...) quanto a arquivos de projeto.

Correção: Reconcilie com atividades recentes claude_file_uploaded ou claude_file_deleted. Se o arquivo foi excluído, o binário não existe mais; o registro de atividade permanece no feed durante a janela de retenção de 6 anos.

Projeto não encontrado

Type: not_found_error

No project is found with the provided id.

Causa: O ID do projeto não existe ou foi excluído.

Correção: Reconcilie com atividades recentes claude_project_created ou claude_project_deleted. O Activity Feed continua a expor os eventos do ciclo de vida do projeto mesmo depois que o próprio projeto não existe mais.

Documento de projeto não encontrado

Type: not_found_error

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

Causa: O ID do documento de projeto não existe ou foi excluído. Esse erro se aplica a documentos de texto de projeto (claude_proj_doc_...), não a arquivos de projeto.

Correção: Use GET /v1/compliance/apps/projects/{project_id}/attachments para listar os anexos atuais. Se o documento estiver ausente, ele foi excluído; recupere-o por meio de um registro de atividade claude_project_document_uploaded se você precisar apenas dos metadados.

Organização, função ou grupo não encontrado

Type: not_found_error

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

Os endpoints de organização, função e grupo retornam um 404 not_found_error no formato de erro padrão. A mensagem de organização nomeia o org_uuid; as mensagens de função e grupo são genéricas (Role not found., Group not found.). Isso ocorre quando um ID de caminho (org_uuid, role_id ou group_id) não existe ou não pertence mais a uma árvore que a chave chamadora pode ler.

Causa: O ID no caminho não corresponde a um registro legível por meio da Compliance API. Funções e grupos podem ser excluídos, e organizações podem ser desvinculadas da árvore pai.

Correção: Verifique o ID em relação ao endpoint de listagem correspondente e reconcilie com atividades recentes de organização, função ou grupo no Activity Feed.

409 Conflict

A requisição está bem formada e autorizada, mas conflita com o estado atual do recurso.

Projeto tem chats anexados

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} foi chamado em um projeto que ainda tem chats anexados.

Correção: Liste os chats do projeto com GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} (o endpoint de listagem de chats exige pelo menos um valor user_ids[]; enumere IDs por meio de Listar usuários da organização), exclua cada um com DELETE /v1/compliance/apps/chats/{claude_chat_id} e, em seguida, tente novamente a exclusão do projeto.

429 Too Many Requests

As requisições à Compliance API são limitadas a 600 requisições por minuto por organização pai. O limite é um único orçamento compartilhado entre todas as chaves sob a organização pai (Compliance Access Keys e as chaves da Admin API de todas as organizações vinculadas) e entre todos os endpoints /v1/compliance/*. Entre em contato com seu representante da Anthropic se sua integração precisar de um limite maior.

Depois que sua chave de API é autenticada, cada resposta da Compliance API inclui os cabeçalhos de resposta de limite de taxa padrão para que seu cliente possa limitar proativamente em vez de esperar por um 429:

• anthropic-ratelimit-requests-limit é o orçamento de requisições por minuto da sua organização pai.
• anthropic-ratelimit-requests-remaining é o orçamento restante na janela atual.
• anthropic-ratelimit-requests-reset é o timestamp RFC 3339 de quando a janela é redefinida e o orçamento completo é restaurado.

Uma resposta 429 também carrega um cabeçalho retry-after com o número de segundos a aguardar antes de enviar a próxima requisição. Esse valor pode incluir uma pequena margem de segurança além de anthropic-ratelimit-requests-reset; respeite o 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: Sua organização pai enviou mais de 600 requisições para /v1/compliance/* em uma janela de 1 minuto, entre todas as suas chaves e organizações vinculadas.

Correção: Aguarde o número de segundos no cabeçalho retry-after e, em seguida, tente novamente. Se o cabeçalho estiver ausente (por exemplo, removido por um intermediário), recorra ao backoff exponencial (comece em 1 segundo, dobre até 60 segundos). Não avance seu cursor de paginação em um 429: a requisição que falhou não retornou dados, então o cursor da última página bem-sucedida ainda está correto.

Requisições que falham na autenticação (uma chave ausente ou não reconhecida, ou uma chave da Claude API em vez de uma Compliance Access Key ou chave da Admin API) são rejeitadas antes do limitador de taxa e não consomem cota. Uma chave válida que não possui o escopo exigido pelo endpoint consome uma unidade de cota antes de o 403 ser retornado.

Se você consulta o Activity Feed em um cronograma, orce sua taxa agregada de requisições (entre todas as chaves, organizações vinculadas e workers concorrentes) abaixo do limite da organização pai. Observe anthropic-ratelimit-requests-remaining para desacelerar antes de atingi-lo. Consulte Projetar sua integração de conformidade para escolher entre consulta por janela e ingestão orientada por cursor.

500 Internal Server Error

Um 500 da Compliance API carrega um cabeçalho de resposta x-should-retry: false quando a falha é determinística. Os SDKs da Anthropic respeitam esse cabeçalho automaticamente. Se você usa uma biblioteca genérica de retry HTTP que tenta novamente em todo 5xx, suprima as tentativas quando x-should-retry for false; tentar novamente esse erro falha de forma idêntica em todas as tentativas.

Um 500 sem o cabeçalho x-should-retry: false é transitório: tente novamente com backoff exponencial (comece em 1 segundo, dobre até 60 segundos). O mesmo se aplica a respostas 502, 503, 504 e 529. Consulte Erros para a semântica de retry de toda a plataforma.

Para incidentes em todo o serviço, verifique status.anthropic.com.

Tamanho máximo de resposta excedido

Type: api_error

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

Causa: Um endpoint de listagem sem paginação (notavelmente GET /v1/compliance/organizations) teria retornado mais do que seu limite rígido de 1.000 registros.

Correção: O endpoint de organizações retorna a árvore completa em uma única chamada, até 1.000 organizações vinculadas. Se sua árvore exceder 1.000, entre em contato com o suporte da Anthropic para obter assistência com listas de organizações maiores. Se você estava consultando esse endpoint para rastrear mudanças de associação de organização, a relistagem periódica continua sendo a abordagem mais confiável depois que o limite for resolvido; ela captura adições e remoções independentemente de qual lado do relacionamento pai-filho as iniciou. O Activity Feed também expõe eventos de associação por meio dos tipos de atividade org_deletion_requested, org_deleted_via_bulk, org_parent_join_proposal_created e org_join_proposal_decided, que você pode usar para acionar uma relistagem imediata em vez de esperar pelo próximo intervalo de consulta.

Próximos passos