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.