Erreurs et limites de fréquence des requêtes

Format des erreurs

Toutes les erreurs de l’API renvoient du JSON avec la structure suivante :

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

Certains points de terminaison (comportement par défaut de Django REST Framework) peuvent aussi renvoyer :

{
  "detail": "Error message"
}

Codes de statut HTTP

Statut	Signification	Cas de figure
200	Succès	La requête a abouti
400	Requête incorrecte	Paramètres manquants ou non valides
401	Non authentifié	Jeton d’authentification manquant, expiré ou non valide
403	Accès interdit	Le jeton ne possède pas la portée requise ou ne permet pas d’accéder à l’espace de travail
404	Ressource introuvable	La ressource n’existe pas ou l’espace de travail ne contient aucune donnée synchronisée
405	Méthode non autorisée	Méthode HTTP incorrecte pour ce point de terminaison
422	Entité non traitable	Échec de la validation du corps de la requête
429	Trop de requêtes	Limite de fréquence des requêtes dépassée
500	Erreur interne du serveur	Erreur inattendue du serveur
503	Service indisponible	Elasticsearch ou une autre dépendance est indisponible

Limites de fréquence des requêtes

API V1 (jetons de service)

Niveau	Limite	Périmètre
Rafale	20 requêtes / 10 secondes	Par jeton
Fenêtre	600 requêtes / 15 minutes	Par jeton

API utilisateur (JWT)

Niveau	Limite	Périmètre
Authentifié	100 requêtes / minute	Par utilisateur
Anonyme	20 requêtes / minute	Par adresse IP

En-têtes de limitation de la fréquence des requêtes

Lorsque les requêtes sont limitées en fréquence, la réponse inclut :

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

Gestion des limites de fréquence des requêtes : Attendez la durée indiquée par Retry-After (en secondes) avant de réessayer. En cas de réponses 429 répétées, augmentez de façon exponentielle le délai d’attente entre les tentatives.

Cas d’erreur courants

Erreurs d’authentification

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

Erreurs d’autorisation

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

Erreurs de validation

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

Erreurs liées aux ressources

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

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

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