Fehlercodes

Referenzliste der octoja-Fehlercodes mit Erläuterungen und Schritten zur Fehlerbehebung.

Diese Referenz listet die Fehlercodes auf, die bei der Arbeit mit der octoja-API auftreten können.

HTTP-Statuscodes

CodeBedeutungMaßnahme
200OKAnfrage erfolgreich
204No ContentAktion erfolgreich, ohne Response Body (z. B. Löschvorgang)
400Bad RequestEin Pflichtfeld fehlt oder ein Wert ist ungültig — detail im Response Body prüfen
401UnauthorizedAnmeldedaten fehlen, sind falsch oder das Token ist abgelaufen — erneut authentifizieren
403ForbiddenAuthentifizierung erfolgreich, aber die Aktion ist nicht erlaubt. Häufige Ursachen: unzureichende Berechtigungen oder ein TOTP-Code ist erforderlich, wurde aber nicht übermittelt
404Not FoundDie Ressource existiert nicht oder es besteht kein Zugriff darauf
409ConflictDie Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource. Häufige Ursachen: Ein Wert, der eindeutig sein muss, wird bereits verwendet (z. B. eine ID für ein benutzerdefiniertes Paket), oder die Ressource befindet sich in einem Zustand, der die Aktion nicht zulässt (z. B. ein Gerät im Wartungsmodus oder eine Paketversion, deren Upload noch nicht abgeschlossen ist)
500Server ErrorEin unerwarteter Fehler ist aufgetreten — erneut versuchen oder den Support kontaktieren

Auch gleichzeitige Änderungen an derselben Ressource können 409 Conflict auslösen. Lade in diesem Fall den aktuellen Stand neu, gleiche deine gewünschte Änderung damit ab und sende sie erst dann erneut. Wiederhole nicht blind denselben Schreibvorgang. Diese Konfliktantwort verwendet application/problem+json und enthält eine traceId, die du bei einer Support-Anfrage mitgeben kannst.

Format der Fehlerantwort

Die meisten Fehlerantworten folgen RFC 7807 Problem Details und enthalten vier Felder:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Customer name is required."
}
FeldBeschreibung
typeURI-Referenz, die den Problemtyp identifiziert
titleKurze, menschenlesbare Zusammenfassung des Problemtyps
statusDer HTTP-Statuscode
detailMenschenlesbare Beschreibung dieses konkreten Vorfalls

Ausnahme: Anfragen, die an der Authentifizierung scheitern (fehlendes oder abgelaufenes Session-Cookie), antworten mit 401 Unauthorized, leerem Body und ohne application/problem+json-Content-Type. Behandle jeden 401 als „erneut authentifizieren“, ohne ein Problem-Details-Payload zu erwarten.

TOTP-Zwei-Schritt-Login

Wenn ein Benutzer die Zwei-Faktor-Authentifizierung aktiviert hat, erfordert der Login zwei Anfragen. Der Login-Endpoint und seine Request-Felder sind unter API-Authentifizierung dokumentiert.

  1. Sende mailAddress und password. Der Server antwortet mit 403 und detail: "TOTP code required." — das ist erwartet und kein Fehler.
  2. Sende erneut mit mailAddress, password und dem aktuellen TOTP-Code. Ein korrekter Code liefert Tokens zurück, ein falscher Code 401.