Doku-Vollausbau: 62 Seiten (Projekt/Admin/Anwender/Referenz), Hook-Referenz mit Signaturen, Corporate-Screenshots, Coverage-Inventar

- Einstieg: Schnellstart + Neues Projekt aus Starter-Skill, Was-ist-Tibi mit Backend/Website-Trennung
- Projekt: Sammlungen, Felder, Abfragen, Rechte, Hooks, Dateien, i18n, Suche, SSR, Pagebuilder, Jobs, Audit, Deploy, LLM, MCP
- Hook-Referenz: 66 Symbole mit Signatur + Beispiel + Fehlerfall (5 Kapitel)
- Admin: Ansichten, Editor, Medien, Exporte, Aktionen, Rechte, KI, Setup, Customizing
- Anwender: 11 Anleitungen im professionellen Du-Ton, 30 Corporate-Screenshots
- Referenz: Schemas, Token-Köpfe, Fehlerbilder, Shortcuts, OpenAPI-Platzhalter
- ADR-0001 bis 0003, Coverage-Skript (282 Items) + Map, Plan-Dateien

src/content/docs/reference/fehlercodes.md

@@ -0,0 +1,54 @@
+---
+title: 'Fehlerbilder'
+description: '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](/projekt/hooks-schreiben/)).
+
+## Tabelle: Fehler zu Ursache zu Fix
+
+| 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 |
+
+<Aside type="caution" title="Legacy ist Default">
+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`).
+</Aside>
+
+```text title="Fehlerbild einordnen"
+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 68b42785 2026-10-15 (tibi-server)