Fehler & Anfragelimits

Fehlerformat

Bei allen API-Fehlern wird JSON mit dieser Struktur zurückgegeben:

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

Einige Endpunkte (mit den Standardeinstellungen des Django REST Framework) können auch Folgendes zurückgeben:

{
  "detail": "Error message"
}

HTTP-Statuscodes

Status	Bedeutung	Wann
200	OK	Anfrage erfolgreich
400	Ungültige Anfrage	Fehlende oder ungültige Parameter
401	Nicht authentifiziert	Authentifizierungstoken fehlt, ist abgelaufen oder ungültig
403	Zugriff verweigert	Token hat nicht den erforderlichen Berechtigungsumfang oder keinen Zugriff auf den Workspace
404	Nicht gefunden	Ressource existiert nicht oder der Workspace enthält keine synchronisierten Daten
405	Methode nicht erlaubt	Falsche HTTP-Methode für den Endpunkt
422	Nicht verarbeitbare Entität	Validierung des Anfrageinhalts fehlgeschlagen
429	Zu viele Anfragen	Anfragelimit überschritten
500	Interner Serverfehler	Unerwarteter Serverfehler
503	Dienst nicht verfügbar	Elasticsearch oder eine andere Abhängigkeit ist ausgefallen

Anfragelimits

V1-API (Service-Tokens)

Kategorie	Limit	Geltungsbereich
Kurzzeitlimit	20 Anfragen / 10 Sekunden	Pro Token
Zeitfenster	600 Anfragen / 15 Minuten	Pro Token

Benutzer-API (JWT)

Kategorie	Limit	Geltungsbereich
Authentifiziert	100 Anfragen / Minute	Pro Benutzer
Anonym	20 Anfragen / Minute	Pro IP

Header für Anfragelimits

Wenn eine Anfrage aufgrund eines Anfragelimits begrenzt wird, enthält die Antwort Folgendes:

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

Umgang mit Anfragelimits: Warte die in Retry-After angegebene Zeit (in Sekunden) ab, bevor du es erneut versuchst. Implementiere bei wiederholten 429-Antworten exponentiell steigende Wartezeiten.

Häufige Fehlerszenarien

Authentifizierungsfehler

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

Berechtigungsfehler

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

Validierungsfehler

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

Ressourcenfehler

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

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

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