Fehlerbehandlung & HTTP-Status

HTTP · Status-Codes · Error-Handling

Fehlerbehandlung

Die API verwendet Standard HTTP-Status-Codes und strukturierte JSON-Fehlermeldungen für konsistente Fehlerbehandlung.

HTTP Status-Codes

Code	Status	Beschreibung
200	OK	Request erfolgreich (GET, POST, DELETE)
201	Created	Neue Ressource erstellt (POST)
400	Bad Request	Ungültiger Request-Body oder fehlende Parameter
401	Unauthorized	Kein oder ungültiges Token
403	Forbidden	Token hat nicht die benötigten Scopes
404	Not Found	Ressource nicht gefunden
409	Conflict	Ressource kann nicht gelöscht werden (Safety-Check)
429	Too Many Requests	Rate-Limit überschritten
500	Internal Server Error	Serverfehler

Fehler-Response-Format

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The access token is invalid or expired"
  }
}

Seit v2.119.0 nennt die API bei einem abgewiesenen Aufruf den Grund zusätzlich im Feld reason und im Header X-XoPort-Deny-Reason, zum Beispiel deny_token_required (401, Aufruf ohne Token) oder deny_ip_not_listed (403, Adresse nicht in XOPORT_REST_IP_LIST).

Häufige Fehler-Codes

Code	HTTP	Beschreibung
`INVALID_GRANT_TYPE`	400	grant_type muss "client_credentials" sein
`INVALID_CLIENT`	401	Client-ID oder Secret ungültig
`INVALID_TOKEN`	401	Token ungültig oder abgelaufen
`MISSING_TOKEN`	401	Kein Authorization-Header
`IP_NOT_ALLOWED`	403	Aufruf von einer Adresse, die nicht in `XOPORT_REST_IP_LIST` steht (seit v2.119.0)
`INSUFFICIENT_SCOPE`	403	Token hat nicht den benötigten Scope
`NOT_FOUND`	404	Ressource nicht gefunden
`HAS_SUBCATEGORIES`	409	Kategorie hat Unterkategorien
`HAS_PRODUCTS`	409	Kategorie enthält Produkte
`HAS_ARTICLES`	409	News-Kategorie enthält Artikel
`HAS_ORDERS`	409	Kunde hat Bestellungen
`RATE_LIMIT_EXCEEDED`	429	Zu viele Requests

Best Practice

Prüfen Sie immer das success-Feld in der Response und implementieren Sie Retry-Logik für 429 und 5xx Fehler.

Fehlerbehandlung & HTTP-Status