Fehler

Jeder Fehler kommt in derselben Hülle:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Für diesen Aufruf fehlt der Bereich „material:write“.",
    "details": { }
  }
}

• code ist englisch, maschinenlesbar und stabil – darauf prüft ein Werkzeug.
• message ist deutsch und für Menschen gedacht – die gehört ins Log oder in die Fehlermeldung der eigenen Oberfläche.
• details steht nur bei manchen Fehlern und nennt Feld oder Ursache.

Alle Codes

Status	Code	Bedeutung	Abhilfe
400	bad_request	Die Anfrage passt fachlich nicht (z. B. Enddatum vor Startdatum, updated_since auf einer Liste ohne Zeitfeld)	Die Meldung nennt den Grund
400	validation_failed	Ein Feld hat das falsche Format	details.fieldErrors nennt Feld und Grund
401	missing_token	Kein Authorization: Bearer … im Kopf	Header setzen
401	invalid_token	Schlüssel unbekannt oder widerrufen	Neuen Schlüssel erzeugen
401	token_expired	Schlüssel abgelaufen	Neuen Schlüssel erzeugen (max. 183 Tage)
403	insufficient_scope	Dem Schlüssel fehlt der Bereich	Erst die Obergrenze des Vereins prüfen, dann den Schlüssel – /me zeigt, was wirklich wirkt
404	not_found	Diesen Datensatz oder Endpunkt gibt es nicht	Pfad und Kennung prüfen
404	api_not_enabled	Die Schnittstelle ist für diese Instanz nicht freigeschaltet	Zugang beantragen bzw. freigeben
409	conflict	Der Zustand passt nicht (z. B. Statuswechsel nicht erlaubt, Bestätigung liegt schon als Beleg vor)	Aktuellen Stand lesen und neu entscheiden
409	not_available	Material oder Fahrzeug ist im Zeitraum bereits vergeben	details.konflikte nennt die Gründe
413	too_large	Die Datei überschreitet die Obergrenze	Grenzen siehe Konventionen
429	rate_limited	Zu viele Anfragen	RateLimit-Reset Sekunden warten
500	internal_error	Serverfehler	Nichts am Aufruf; die Details stehen im Server-Log

Bei 401 trägt die Antwort zusätzlich den Kopf WWW-Authenticate: Bearer.

Warum ein 500er nichts verrät

Treiber- und SQL-Meldungen verraten Tabellennamen und Struktur. Nach außen geht deshalb nur „Interner Serverfehler“ – vollständig steht der Fehler im Server-Log der Instanz (Bereich api-v1), mit Methode und Pfad.

Sonderfall: 409 not_available

Der Verleih prüft jeden Zeitraum gegen andere Ausleihen und Packlisten. Bei einem Konflikt kommt kein stiller Erfolg, sondern:

{
  "error": {
    "code": "not_available",
    "message": "Bulli ist vom 14.08. bis 16.08. bereits vergeben.",
    "details": { "konflikte": ["Bulli ist vom 14.08. bis 16.08. bereits vergeben."] }
  }
}

Geprüft wird beim Anlegen, beim Ändern und noch einmal beim Bestätigen – zwischen Anfrage und Bestätigung kann jemand anderes gebucht haben. Wer die Konflikte vorab wissen will, ohne etwas anzulegen, nimmt POST /verleih/pruefen.

Sonderfall: 400 auf einer Liste

Zwei Fälle, die zunächst überraschen und beide Absicht sind:

• updated_since auf einer Liste ohne Zeitfeld (z. B. der Sachstand der Nachweise). Eine leere Liste würde ein Abgleich-Werkzeug für immer verstummen lassen.
• updated_since mit ungültigem Zeitpunkt. Erwartet wird ISO 8601, etwa 2026-07-01T00:00:00Z.

Diagnose in vier Schritten

1. GET /me – kommt hier 401, liegt es am Schlüssel, nicht am Endpunkt.
2. scopes in der Antwort vergleichen – steht dort weniger als erwartet, fehlt die Freigabe des Bereichs in Einstellungen → API, nicht das Recht am Schlüssel.
3. Denselben Aufruf mit -i wiederholen und auf RateLimit-Remaining sehen.
4. Server-Log der Instanz (Bereich api-v1): abgelehnte Zugänge, gedrosselte Anfragen und abgewiesene Eingaben stehen dort mit Pfad und Grund.