23. Errors

Fehlerformat der öffentlichen Endpunkte

Die Endpunkte aus 20-api.md antworten konsistent mit einem JSON-Objekt, das mindestens ein status-Feld enthält. Es gibt kein einheitliches globales Fehlerschema mit Fehlercode — jeder Endpunkt definiert seine eigenen status-Werte, passend zu seiner Domäne:

{ "status": "fehler", "detail": "Bitte alle Pflichtfelder ausfüllen." }

Gebräuchliche status-Werte je nach Endpunkt: ok, fehler, nicht_gefunden, belegt (Buchungsseiten: Slot vergeben), rate_limit, spam (wird absichtlich wie ok behandelt, siehe 24-rate-limits.md), bestaetigung_erforderlich (Newsletter Double-Opt-in).

HTTP-Statuscodes

Code	Bedeutung
`200`	Erfolgreich (auch bei als Spam erkannten Einsendungen — bewusst, siehe 24-rate-limits.md)
`400`	Pflichtfelder fehlen oder Anfrage ist nicht auswertbar (z. B. ungültiges JSON)
`401`	Fehlender/ungültiger Bearer-Token bei internen, authentifizierten Routen
`403`	Zugriff verweigert — z. B. Domain nicht freigegeben (Chat-Widget) oder Plan reicht nicht (siehe unten)
`404`	Ressource existiert nicht (Buchungsseite, Formular, Widget)
`409`	Konflikt — z. B. Zeitslot bereits gebucht
`429`	Echtes Rate-Limit erreicht
`500`	Unerwarteter Serverfehler
`503`	Feature global deaktiviert oder benötigte Konfiguration fehlt

Plan-Gating-Fehler (interne, eingeloggte Aktionen)

Reicht der Plan des Kontos für eine Funktion nicht aus (siehe 26-billing.md), wirft der Server einen FeatureNotAvailableError mit einer für Endnutzer verständlichen Meldung, z. B.:

Dieses Feature ist in Ihrem aktuellen Plan nicht enthalten. Bitte upgraden Sie unter Abrechnung. (Feature: ai)

Dies wird ausschließlich serverseitig anhand der authentifizierten userId geprüft — nie anhand eines vom Client mitgesendeten Plan-Werts.

Fehlerhinweis für externe Formular-/Kalender-Einbindungen

Da /api/public/formulare/submit mit multipart/form-data arbeitet, führt fehlendes Content-Type-Handling im eigenen Code meist zu 400 { "status": "fehler" } — beim manuellen Nachbauen des Requests (statt Browser-FormData) unbedingt echten Multipart-Body senden, kein JSON.