Fehler & Statuscodes

Fehlerformat

Fehler werden immer als JSON-Objekt mit einem message-Feld zurückgegeben:

{
  "message": "Access to the requested resource is denied."
}

Aus Sicherheitsgründen werden serverseitige Fehlerdetails nicht nach außen gegeben – bei 5xx-Fehlern wird stets eine generische Meldung zurückgegeben.

Statuscodes

Status	Bedeutung	Typische Ursache
200	OK	Request erfolgreich
200	OK (mit message)	Einzelne Endpunkte melden "bereits erledigt"-Zustände als 200 mit message
302	Redirect	Endpunkt leitet auf eine Download-URL weiter (z. B. Datei-Downloads), Location-Header beachten
400	Fachlicher Fehler	Vorbedingung nicht erfüllt (z. B. Status verbietet die Aktion)
403	Zugriff verweigert	Ungültige/abgelaufene HMAC-Signatur, wiederverwendete hmac_unique, fehlende Rechte, Origin nicht freigegeben oder Verbindung von der Kund:in gelöscht bzw. Zugang gesperrt
404	Nicht gefunden	Angefragte Ressource existiert nicht
406	Validierungsfehler	Request-Parameter ungültig – die message enthält ein JSON-Array mit {field, value, rule, params} pro verletztem Feld
409	Konflikt	Aktueller Zustand passt nicht zur Aktion, z. B. Aktivierung beim Pairing noch ausstehend (codesetup/get), Auto-Sync bereits aktiv oder Tarif-Limit erreicht
410	Gone	Einmal-Ressource abgelaufen (z. B. codesetup, datahandler)
422	Unprocessable Entity	Fachlicher Zustand verhindert die Aktion (z. B. ungültiger Status-Übergang)
423	Locked	Ressource ist schreibgeschützt (z. B. geschützte Datei)
500	Serverfehler	Interner Fehler, generische Meldung
501	Nicht implementiert	Bereich oder Aktion existiert nicht
503	Rate Limit	Zu viele Anfragen – siehe unten

Rate Limiting

Die API limitiert eingehende Requests auf 250 Requests pro Sekunde und IP-Adresse. Bei Überschreitung antwortet der vorgeschaltete Proxy mit 503.

Fehlerbehandlung im Client

200          → Response verarbeiten
302          → Location-Header folgen (manuelle Weiterleitung)
403          → HMAC-Signatur, Zeitstempel und Origin prüfen; stimmt alles, hat die Kund:in
               die Verbindung evtl. gelöscht (mein.ebonaut.de) – nicht erneut senden
406          → message der Nutzer:in anzeigen / Request korrigieren
409          → bei codesetup/get: weiter pollen; sonst Zustand der Ressource prüfen
500/501/503  → mit Backoff wiederholen, bei Dauerfehler Support kontaktieren