Fehler

Format

Fehler der API sind JSON:

{
  "status_code": 404,
  "detail": "Not Found",
  "extra": {}
}

Feld	Bedeutung
status_code	HTTP-Statuscode, identisch mit dem der Antwort
detail	Kurze Meldung in englischer Sprache. Für Menschen gedacht, nicht für Auswertung.
extra	Optional. Maschinenlesbare Details, oft mit einem Code in extra.error. Werte auswerten, nie detail.

Unterscheide Fälle über extra.error. Jede Operation in der Referenz nennt ihre Codes.

Statuscodes

Status	Bedeutung	Wiederholen?
400	Die Anfrage ist formal falsch oder erfüllt eine Regel nicht (fehlendes Feld, falscher Typ, ungültiger Wert). extra.error nennt, wenn vorhanden, den Grund.	Nein, erst korrigieren
401	Nicht angemeldet oder Token ungültig oder abgelaufen	Nein, siehe Anmeldung
403	Keine passende Berechtigung oder Schlüssel widerrufen	Nein, siehe Scopes
404	Gibt es nicht oder gehört einem anderen Konto	Nein
409	Konflikt mit dem aktuellen Zustand, etwa eine Aktion, die im Status der Ressource nicht mehr geht. extra.error nennt den Grund.	Erst Zustand neu lesen
413	Upload zu groß	Nein, Datei verkleinern
422	Die Anfrage ist verständlich, kann aber fachlich nicht ausgeführt werden, zum Beispiel Vorschau-Fehler oder IDEMPOTENCY_KEY_REUSED	Nein, erst korrigieren
429	Zu viele Anfragen, siehe Mengenbegrenzung	Ja, nach Wartezeit
5xx	Fehler oder Störung auf Shirtee-Seite	Ja, mit Backoff

Wiederholen

• Wiederhole nur 429 und 5xx, mit wachsendem Abstand (Backoff) und einer Obergrenze.
• Wiederhole schreibende Aufrufe nur, wenn sie wiederholbar sind. Für die Bestellanlage gilt: Idempotency-Key.
• Plattform-Fehler kommen nicht immer als JSON an. Ein 502 oder 504 kann eine Fehlerseite im HTML-Format sein. Werte zuerst den Statuscode aus, dann erst den Inhalt.

Antwort lesen

Prüfe den Statuscode, bevor du den Inhalt als JSON parst. Dein Client sollte unbekannte Felder in Antworten ignorieren, siehe Stabilität und Änderungen.