Zum Inhalt springen

Fehler und Limits

Fehler sind RFC 9457 application/problem+json:

{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "no such route"
}

detail ist nur da gesetzt, wo die Meldung sicher ausgegeben werden kann. Backend-Meldungen werden nie durchgereicht.

Status Bedeutung
400 Request-Validierung fehlgeschlagen, oder ein abgelehnter Schreibzugriff mit sicherer Meldung
401 Fehlendes oder ungültiges Bearer-Token; trägt WWW-Authenticate
402 Plan oder Kontingent hat den Aufruf abgelehnt
403 Die Rolle api_user darf diese Operation nicht ausführen
404 Route oder Ressource existiert nicht
409 Zustandskonflikt, von einer upstream Action gemeldet
413 Request-Body über dem Limit
422 Nicht verarbeitbarer Inhalt, von einer upstream Action gemeldet
500 Ein interner API-Fehler, auch bei einer Anfrage, die nicht zum Backend-Schema passt
502 Das Backend ist auf eine Weise fehlgeschlagen, die der Vertrag nicht abdeckt
503 Der Authentifizierungsdienst ist nicht erreichbar; später erneut versuchen

Jede Antwort trägt einen x-request-id-Header. Gib ihn an, wenn du ein Problem meldest.

Schreibzugriffe mit shop_url oder outside_eu_forward_href liefern 400 mit einer Erklärung. Passt eine API-Anfrage nicht zum Backend-Schema, liefert sie 500. Das bedeutet nicht, dass deinem Token eine Berechtigung fehlt.

Listen-Endpunkte nehmen limit (1 bis 100) und offset (Standard 0). Der Standard ist 50 für Workspaces, Brands und Labels und 20 für Marketing-QR-Codes und die Kataloge.

Brands, Labels und Marketing-QR-Codes melden ein total:

{ "items": [], "limit": 50, "offset": 0, "total": 137 }

Workspaces und die Referenzkataloge melden stattdessen has_more:

{ "items": [], "limit": 50, "offset": 0, "has_more": true }

has_more: true heißt, es gibt mindestens ein weiteres Element. Hole die nächste Seite mit offset plus limit.

Request-Bodies sind auf 256 KB begrenzt. Ein größerer Body wird mit 413 abgelehnt.

Die API selbst setzt kein Rate-Limit pro Aufrufer. Requests können am CDN-Edge pro Client-IP begrenzt werden; bei einer Ablehnung warte kurz und versuche es erneut.