tibi-docs/src/content/docs/reference/fehlercodes.md

title, description

title	description
Fehlerbilder	Typische Antworten und was sie bedeuten: project not found, permission denied, 409, Validierung.

import { Aside } from '@astrojs/starlight/components';

Jede Antwort folgt dem Muster {"error": "<text>"}. Status plus Text verraten dir Ursache und Fix. Alle Texte unten stehen wörtlich so im Code (internal/controller/*.go, validator.go). Das gilt für API-Antworten — wirfst du selbst im Hook, steuert msg den Fehlertext und json den Körper (ohne json echot der Server dein geworfenes Objekt; siehe Hooks schreiben).

Fehlerübersicht

Status	Antwort	Ursache	Fix
404	project not found	Projekt läuft auf diesem Server nicht (nicht registriert oder falscher Namespace)	Projekt per JWT registrieren, dann Reload (siehe Token-Köpfe)
404	document not found / not found	Datensatz-ID existiert nicht in dieser Collection	ID und Collection-Namen prüfen
403	permission denied	Kopf fehlt, Wert falsch oder Methode nicht erlaubt	Header-Namen, Token-Wert und permissions-Block prüfen
403	permission denied: …	Detail steht nach dem Doppelpunkt, z. B. fehlender Scope oder Bulk-Recht	Text nach dem Doppelpunkt lesen: Scope nachtragen oder Einzel- statt Bulk-Route nutzen
403	aggregate permission denied / lookup permission denied	Aggregation oder Lookup ohne Recht	permissions-Eintrag für diese Operation ergänzen
403	permission denied for given projection	Angeforderte Projektion nicht erlaubt	Projektion aus der Anfrage entfernen oder freigeben
409 / 500	Doppelter Schlüssel (Konflikt)	Eindeutiger Index verletzt, z. B. path+lang doppelt. Achtung Default: Standard ist Legacy-Modus (legacy.httpCodes), dort antwortet der Server 500 statt 409; 409 gibt es nur im modernen Modus	Eindeutiges Feld ändern; bei 500 denselben Fall annehmen
400 / 422	validation failed + Feldliste	Datensatz verstößt gegen Feld-Validatoren. Legacy-Default: 400; modern: 422	code je Feld aus der zweiten Tabelle lesen
400	invalid data type for data in return of … hook	Hook gab falschen Typ zurück	Hook-Rückgabe auf Objekt bzw. erwarteten Typ fixen

Validierungs-Codes je Feld

Der Server liefert zu jedem Feld {"code": "…", "message": "…"}. Alle Codes aus validator.go:

Code	Bedeutung	Typisches Beispiel
required	Pflichtfeld fehlt oder leer	Leerer Titel bei Pflichtfeld
type	Falscher Datentyp	Array statt String; Zahl statt Bool
format	Format falsch	email, url, uuid, slug verletzt
pattern	Regulärer Ausdruck passt nicht	validator.pattern greift nicht
min_length / max_length	String zu kurz oder zu lang	Titel über dem Limit
min / max	Zahl zu klein oder zu groß	Preis unter Minimum
min_date / max_date	Datum außerhalb des Fensters	Datum vor minDate
min_items / max_items	Array hat zu wenige oder zu viele Einträge	Leere Liste bei minItems: 1
in	Wert nicht in der Allow-Liste	Status nicht in validator.in
eval	Eigene JS-Prüfung schlägt fehl	message enthält den Hook-Text
unknown_field	Feld steht nicht im Schema (nur bei strictFields)	Tippfehler im Feldnamen
internal	Validator selbst defekt, z. B. eval nicht kompiliert	Config und Server-Logs prüfen

Ohne `legacy.httpCodes: false` in der Projekt-Config gelten die alten Codes: Konflikt = **500** (nicht 409), Validierung = **400** (nicht 422). Wenn du 500 siehst, wo du 409 erwartest, ist das kein Bug — das ist der Default (`internal/controller/http_status.go`).

400/422 validation failed ──▶ code lesen ──▶ Feld fixen ──▶ erneut senden
403 permission denied ──▶ Doppelpunkt-Text lesen ──▶ Kopf oder Recht fixen
404 project not found ──▶ registrieren + Reload ──▶ erneut senden
409/500 Konflikt ──▶ eindeutiges Feld ändern ──▶ erneut senden

Verifiziert am 68b4278 2026-10-15 (tibi-server)