Erros & limites de requisições

Formato dos erros

Todos os erros da API retornam JSON com esta estrutura:

{
  "error": "Short error description",
  "detail": "Extended description (optional)"
}

Alguns endpoints (com as configurações padrão do Django REST Framework) também podem retornar:

{
  "detail": "Error message"
}

Códigos de status HTTP

Status	Significado	Quando ocorre
200	OK	Requisição bem-sucedida
400	Requisição inválida	Parâmetros ausentes ou inválidos
401	Não autorizado	Token de autenticação ausente, expirado ou inválido
403	Acesso proibido	O token não tem o escopo necessário ou acesso ao espaço de trabalho
404	Não encontrado	O recurso não existe ou o espaço de trabalho não tem dados sincronizados
405	Método não permitido	Método HTTP incorreto para o endpoint
422	Entidade não processável	Falha na validação do corpo da requisição
429	Requisições em excesso	Limite de requisições excedido
500	Erro interno do servidor	Erro inesperado no servidor
503	Serviço indisponível	Elasticsearch ou outra dependência fora do ar

Limites de requisições

API V1 (tokens de serviço)

Categoria	Limite	Escopo
Rajada	20 requisições / 10 segundos	Por token
Janela	600 requisições / 15 minutos	Por token

API de usuário (JWT)

Categoria	Limite	Escopo
Autenticado	100 requisições / minuto	Por usuário
Anônimo	20 requisições / minuto	Por IP

Cabeçalhos de limite de requisições

Quando o limite de requisições é atingido, a resposta inclui:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Como lidar com os limites de requisições: Aguarde o tempo indicado em Retry-After (em segundos) antes de tentar novamente. Implemente uma estratégia de aumento exponencial do tempo de espera para respostas 429 repetidas.

Cenários comuns de erro

Erros de autenticação

// Missing Authorization header
{"detail": "Authentication credentials were not provided."}

// Invalid or expired JWT
{"detail": "Given token not valid for any token type", "code": "token_not_valid"}

// Invalid service token
{"error": "Invalid or revoked service token."}

// Expired service token
{"error": "Token has expired."}

Erros de permissão

// Token missing required scope
{"error": "Token does not have the required scope: graph:search"}

// Workspace not in token's allowed list
{"error": "Workspace not allowed for this token."}

Erros de validação

// Missing required parameter
{"error": "workspace_id is required."}

// Invalid UUID format
{"error": "Invalid node_id format."}

// Query too long (V1 API)
{"error": "Query too long (max 256 characters)."}

// Disallowed characters in query
{"error": "Query contains disallowed characters."}

Erros de recursos

// Workspace not synced
{"error": "No synced data found for this workspace."}

// Node not found
{"error": "Node not found."}

// Elasticsearch unavailable
{"error": "Search service unavailable."}