Fehler und Statuscodes

Die CampOne-API verwendet HTTP-Standardstatuscodes und zwei vorhersehbare JSON-Fehlerformen. Wer diese Seite einmal liest, kann Fehler über alle Endpunkte hinweg einheitlich behandeln.

Aufbau der Fehlerantworten

Bei einem Fehler liefert die API eine von zwei JSON-Formen.

detail auf oberster Ebene

Wird verwendet für Authentifizierung, Autorisierung, Nicht-gefunden, Drosselung, Serverfehler und die meisten domänenbezogenen Fehler:

{ "detail": "invalid_key" }

Der Wert ist entweder ein kurzer Maschinencode (z. B. invalid_key, site_not_found) oder ein menschenlesbarer Satz — siehe die dokumentierten Fehlercodes weiter unten.

Feldbezogene Validierungsfehler

POST-Endpunkte validieren den Anfragekörper vor der Verarbeitung. Schlägt die Validierung fehl, antwortet die API mit 400 Bad Request und einem Eintrag pro fehlerhaftem Feld:

{
  "check_in_date": ["This field is required."],
  "num_adults": ["Ensure this value is greater than or equal to 0."]
}

Jeder Wert ist ein Array von einer oder mehreren Fehlermeldungen für das jeweilige Feld. Auf oberster Ebene kann zusätzlich non_field_errors erscheinen, wenn die Validierungsregel nicht an ein einzelnes Feld gebunden ist.

Statuscode-Referenz

Code	Wann
200 OK	Erfolgreicher GET
201 Created	Erfolgreicher POST, der eine Ressource erzeugt hat
400 Bad Request	Validierungsfehler im Körper oder ein dokumentierter Domänenfehler wie site_not_found
401 Unauthorized	Fehlender, fehlerhafter, abgelaufener oder widerrufener API key
403 Forbidden	Gültiger Schlüssel, aber fehlender Geltungsbereich
404 Not Found	Die Ressource existiert nicht oder gehört zu einem anderen Mandanten
429 Too Many Requests	Pro-Schlüssel-Rate-Limit überschritten — siehe Rate-Limits
500 Internal Server Error	Serverseitiger Fehler — mit exponentiellem Backoff erneut versuchen und bei anhaltendem Auftreten den Support informieren

Dokumentierte Fehlercodes

Die folgenden Codes sind stabile Zeichenketten — Ihr Code kann ohne Parsing der Prosa darauf abgleichen. Alles andere, was in detail landet, ist als generische Meldung zu behandeln, nicht als Vertrag.

Code	Status	Wo
invalid_key	401	Jeder Endpunkt, wenn das Bearer-Token fehlt, fehlerhaft ist oder zu keinem hinterlegten Schlüssel passt
key_inactive	401	Jeder Endpunkt, wenn der Schlüssel widerrufen oder abgelaufen ist
site_not_found	400	POST /api/v1/public/bookings/, wenn site_id zu keinem Stellplatz des aufrufenden Mandanten passt
not_found	404	Detail-Endpunkte (z. B. GET /api/v1/public/bookings/{id}/), wenn die Ressource nicht existiert oder zu einem anderen Mandanten gehört

Mandantenisolation

Jeder API key ist genau an einen Mandanten gebunden. Die API filtert sämtliche Abfragen nach diesem Mandanten, bevor sie die Datenbank erreichen, daher gilt:

• Ein GET auf eine Ressource, die existiert, aber zu einem anderen Mandanten gehört, liefert 404, nicht 403. Die API unterscheidet bewusst nicht zwischen „nicht Ihres” und „existiert nicht” — das würde die Existenz von Ressourcen über Mandanten hinweg preisgeben.
• Ressourcen-IDs sind nicht mandantenübergreifend eindeutig. Buchungs-ID 42 für Mandant A und Buchungs-ID 42 für Mandant B sind unterschiedliche Buchungen. Eine ID, die mit einem Schlüssel ermittelt wurde, hat mit einem anderen Schlüssel keine Bedeutung.
• Ein POST-Körper, der auf eine ID eines anderen Mandanten verweist (z. B. site_id beim Anlegen einer Buchung), wird so zurückgewiesen, als ob die ID nicht existieren würde (400 site_not_found).

Idempotenz

Die aktuelle API-Version (v1) unterstützt keine Idempotenz-Schlüssel. Insbesondere:

• POST /api/v1/public/bookings/ darf nicht blind wiederholt werden — ein Netzwerk-Timeout, der eine erfolgreiche Anlage verdeckt, hinterlässt bei einem Retry eine doppelte Buchung.
• Läuft ein POST in ein Timeout, fragen Sie vor einem erneuten Versuch den Listen-Endpunkt mit passenden Filtern ab, um zu prüfen, ob die Ressource tatsächlich angelegt wurde.

Ein eigener Idempotency-Key-Header steht auf der Roadmap. Bis dahin sind Anlage-Aufrufe als seiteneffektbehaftet zu behandeln und Ihre Retry-Logik entsprechend zu gestalten.