Fehler und Limits

Fehler

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 unerwarteter Fehler innerhalb der API
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.

Pagination

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-Body-Limit

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

Rate-Limits

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.