Fehler

Fehler beantwortet die API mit einem passenden HTTP-Status und einem Körper im Format application/problem+json nach RFC 9457:

{
  "type": "https://www.ladehase.com/de/docs/fehler#invalid_state",
  "title": "Zustand passt nicht",
  "status": 409,
  "code": "invalid_state",
  "detail": "Die Sitzung ist bereits abgerechnet."
}

• code ist stabil und für Programme gedacht. Reagiere in deinem Code auf code, nicht auf title oder detail.
• title und detail sind für Menschen und können sich ändern.
• type verweist auf den passenden Abschnitt dieser Seite.

Codes

invalid_request

Status 400. Die Anfrage ist ungültig, zum Beispiel fehlt ein Pflichtfeld oder ein Wert liegt ausserhalb des erlaubten Bereichs. detail nennt das Feld und den Grund.

unauthorized

Status 401. Der API-Schlüssel fehlt, ist ungültig oder widerrufen. Siehe Authentifizierung.

forbidden

Status 403. Der Schlüssel oder die Person darf diese Aktion nicht ausführen.

not_found

Status 404. Das Objekt gibt es nicht oder es gehört zu einer anderen Organisation beziehungsweise zum anderen Modus (Test oder live).

conflict

Status 409. Die Anfrage widerspricht dem aktuellen Stand, zum Beispiel läuft am Anschluss bereits eine Sitzung.

invalid_state

Status 409. Die Aktion ist im aktuellen Zustand nicht möglich, zum Beispiel eine Rückerstattung vor der Abrechnung. Siehe Sitzungen und Zustände.

device_unavailable

Status 409. Der Ladepunkt ist offline, gesperrt, gestört oder besetzt.

device_error

Status 502. Die Ladestation oder die Cloud des Herstellers hat einen Befehl nicht ausgeführt. Versuch es später nochmals.

payment_error

Status 409 oder 502. Der Zahlungspartner hat die Aktion abgelehnt oder ist nicht erreichbar.

integration_error

Status 502. Die Verbindung zum Hersteller oder Zahlungspartner ist gestört, zum Beispiel weil Zugangsdaten abgelaufen sind. Prüf die Verbindung im Dashboard.

not_supported

Status 400 oder 409. Die Funktion wird für diesen Hersteller, dieses Gerät oder diesen Zahlungspartner nicht unterstützt.

idempotency_conflict

Status 422. Derselbe Idempotency-Key wurde mit anderem Inhalt verwendet. Nimm für jede neue Anfrage einen neuen Schlüssel.

idempotency_in_progress

Status 409. Eine Anfrage mit demselben Idempotency-Key wird noch verarbeitet. Warte kurz und wiederhole.

rate_limited

Status 429. Zu viele Anfragen. Die Kopfzeile Retry-After sagt, wie viele Sekunden du warten sollst.

internal_error

Status 500. Ein unerwarteter Fehler bei uns. Wir werden automatisch benachrichtigt. Wiederhole die Anfrage mit demselben Idempotency-Key.

Richtig reagieren

• Bei 429, 502 und 500 lohnt sich eine Wiederholung mit steigender Wartezeit.
• Bei 400, 401, 403, 404 und 422 ändert eine Wiederholung nichts. Korrigiere die Anfrage.
• Bei 409 liest du das Objekt neu und entscheidest anhand des Zustands.