Errores y límites de frecuencia de solicitudes

Formato de los errores

Todos los errores de la API devuelven JSON con esta estructura:

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

Algunos puntos de conexión (con la configuración predeterminada de Django REST Framework) también pueden devolver:

{
  "detail": "Error message"
}

Códigos de estado HTTP

Estado	Significado	Cuándo se produce
200	Correcto	La solicitud se ha completado correctamente
400	Solicitud incorrecta	Faltan parámetros o no son válidos
401	No autorizado	Falta el token de autenticación, ha caducado o no es válido
403	Acceso prohibido	El token no tiene el alcance requerido o no permite acceder al espacio de trabajo
404	No encontrado	El recurso no existe o el espacio de trabajo no tiene datos sincronizados
405	Método no permitido	El método HTTP no es correcto para el punto de conexión
422	Entidad no procesable	Ha fallado la validación del cuerpo de la solicitud
429	Demasiadas solicitudes	Se ha superado el límite de frecuencia de solicitudes
500	Error interno del servidor	Se ha producido un error inesperado en el servidor
503	Servicio no disponible	Elasticsearch u otra dependencia no está disponible

Límites de frecuencia de solicitudes

API V1 (tokens de servicio)

Nivel	Límite	Ámbito
Ráfaga	20 solicitudes / 10 segundos	Por token
Ventana	600 solicitudes / 15 minutos	Por token

API de usuario (JWT)

Nivel	Límite	Ámbito
Autenticado	100 solicitudes / minuto	Por usuario
Anónimo	20 solicitudes / minuto	Por IP

Cabeceras de límites de frecuencia de solicitudes

Cuando se aplica una limitación de frecuencia de solicitudes, la respuesta incluye:

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

Cómo gestionar los límites de frecuencia de solicitudes: Espera el tiempo indicado en Retry-After (en segundos) antes de volver a intentarlo. Implementa una espera exponencial entre reintentos si recibes respuestas 429 repetidas.

Casos de error habituales

Errores de autenticación

// 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."}

Errores de permisos

// 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."}

Errores de validación

// 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."}

Errores 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."}