Fehlerbehandlung

Die API verwendet konventionelle HTTP-Statuscodes und gibt strukturierte JSON-Fehlerobjekte zurück.

Fehlerformat

Alle Fehlerantworten folgen einem einheitlichen Format mit einem error-Code und einer lesbaren message:

Fehler-Response400 Bad Request

{
  "error": "validation_error",
  "message": "Das Feld \"datum\" ist erforderlich.",
  "details": {
    "field": "datum",
    "code": "required"
  }
}

HTTP-Statuscodes

Code	Status	Beschreibung
200	OK	Anfrage erfolgreich
201	Created	Ressource erfolgreich erstellt
204	No Content	Erfolgreich, keine Antwortdaten (z.B. DELETE)
400	Bad Request	Ungültige Parameter oder fehlende Pflichtfelder
401	Unauthorized	Fehlender oder ungültiger API-Key
403	Forbidden	Kein Zugriff auf diese Ressource (z.B. fremde Werkstatt)
404	Not Found	Ressource nicht gefunden
409	Conflict	Konflikt (z.B. doppelte Buchung, Zeitslot belegt)
422	Unprocessable Entity	Semantisch ungültige Daten
429	Too Many Requests	Rate Limit überschritten
500	Internal Server Error	Serverfehler — bitte Support kontaktieren

Fehlercodes

Das Feld error enthält einen maschinenlesbaren Fehlercode:

Error Code	HTTP	Beschreibung
`validation_error`	400	Ein oder mehrere Felder sind ungültig
`unauthorized`	401	API-Key fehlt, ist ungültig oder abgelaufen
`forbidden`	403	Kein Zugriff auf die angeforderte Ressource
`not_found`	404	Die angeforderte Ressource existiert nicht
`conflict`	409	Aktion nicht möglich aufgrund eines Konflikts
`rate_limit_exceeded`	429	Zu viele Anfragen pro Minute
`internal_error`	500	Interner Serverfehler

Beispiel: Fehlerbehandlung

# Fehler werden als JSON zurückgegeben:
"token-method">curl -s "token-keyword">-X GET "token-url">https://api.schraubertermin.de/v1/buchungen/ungueltige-id \
  "token-flag">-H 'Authorization: Bearer sk_live_IhrApiKey' | jq .

Paginierung

Listen-Endpunkte unterstützen Paginierung über die Query-Parameter page und per_page.

Paginierte Antwort200 OK

{
  "data": [
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}