Pagination und Fehler

Prüfe sowohl Transportstatus als auch Operationsergebnis. Eine erfolgreiche Anfrage bedeutet nicht, dass jede Stapelzeile erfolgreich war.

Profilpagination

GET /api/v1/profiles unterstützt page, limit und cursor sowie Filter. Das Schema erlaubt limit 1–1000; der CLI-Befehl profiles akzeptiert bewusst 1–100 und verwendet standardmäßig 100. Verwende pinned_first=false für Cursor-Durchläufe. Behalte sort, order und Filter bei, übergib next_cursor unverändert und beende den Durchlauf bei null. Cursors sind nicht mit pinned_first=true kombinierbar. Seiten-/Offsetlisten können sich bei Profiländerungen verschieben; dies ist kein transaktionaler Snapshot.

HTTP

GET /api/v1/profiles?limit=100&pinned_first=false
GET /api/v1/profiles?limit=100&pinned_first=false&cursor=<NEXT_CURSOR>

Kodiere Query-Werte für URLs. Andere Routenfamilien haben eigene Paginationsschemas. Die Transferliste verwendet next mit page oder cursor je nach Anbieter; sie verwendet nicht den nativen Profilcursor.

Natives Fehlerformat

JSON

{
  "error": {
    "code": "auth.scope_missing",
    "message": "Berechtigung fehlt",
    "details": {
      "missing": [
        "profiles:read"
      ]
    }
  },
  "request_id": "example-request-id"
}

Dies ist ein fiktives Strukturbeispiel. Entscheide anhand von error.code und Status, nicht anhand lokalisierter Meldungstexte. Bewahre request_id zur Zuordnung auf, entferne aber Zugangsdaten und persönliche Daten aus Berichten. Stapelendpunkte können einzelne Fehler in einer erfolgreichen HTTP-Antwort liefern: Prüfe results und Fehlerzahlen.

Statusbehandlung

HTTP	Bedeutung und Vorgehen
400	Ungültige Felder oder zustandsabhängige Validierung. Exaktes Schema und Fehlerdetails vergleichen.
401	Fehlendes, abgelaufenes, widerrufenes oder ungültiges Token. Lokalen Zugang korrigieren.
403	Fehlender Scope oder verbotener Browser-Ursprung. Grenze nicht umgehen.
404	Unbekannte Route/Ressource oder nicht verfügbare Transfervorschau. Version und ID prüfen.
409	Konflikt mit aktuellem Zustand. Vor Wiederholung erneut lesen.
413 / 415	Nutzdaten zu groß / Content-Type muss application/json sein.
421	Host-Header ist keine erlaubte lokale Adresse mit Port.
429	Drosselung oder ausgelastete Operation. Retry-After beachten, falls vorhanden.
5xx	Dienst-/Anbieterfehler. Unkritischen Fehlercode festhalten und resultierenden Zustand prüfen.

Zeitlimits und Wiederholungen

Ein Zeitlimit oder eine verlorene Antwort setzt eine Operation nicht zurück. Nach Start-, Erstellungs-, Import- oder Ausführungsanfragen prüfe vor einer Wiederholung den resultierenden Zustand. Dieser Export enthält keinen allgemeinen Idempotency-Key-Vertrag. Native Anfragekörper sind standardmäßig auf 1 MiB begrenzt; ausgewählte Import-/Stapelrouten haben größere Grenzen. Die größere Grenze gilt nicht automatisch für jede Route. Zwanzig fehlgeschlagene lokale Authentifizierungen innerhalb einer Minute lösen eine einminütige Sperre für die Client-IP aus.