Fehler und Limits

Verwaltungsfehler enthalten error (lesbarer Text) und code (stabil). Entscheide anhand von code und HTTP-Status, nicht anhand des Nachrichtentexts. Scope-Fehler können required und missing_scope enthalten; wiederholbare Antworten können retryAfter, retryable und Retry-After enthalten. Eigentumsfehler liefern 404, um Ressourcen anderer Wallets nicht offenzulegen.

{ "error": "Insufficient scope", "code": "insufficient_scope", "required": "write" }

• 400: ungültiges JSON, ungültiger Aufruf oder abgelehntes Ziel.
• 401: fehlende/ungültige Authentifizierung oder abgelehnte Signatur.
• 402: unzureichende Credits oder erforderliche Slot-Kapazität.
• 403: unzureichender Scope oder andere ausdrückliche Berechtigungsgrenze.
• 404: fehlende oder fremde Ressource.
• 409: Konflikt, aktive Idempotency-Reservierung, wiederverwendeter Schlüssel oder pausiertes Asset.
• 410: abgelaufener Auflade-Draft.
• 422: fehlgeschlagene Zahlungsprüfung.
• 429: Rate-Limit oder ausgeschöpfte Security-Rückfallkapazität.
• 503: nicht verfügbarer Preis, Signer oder vorübergehende Abhängigkeit.

Beachte Retry-After und verwende exponentielles Backoff mit Jitter und einer begrenzten Zahl von Versuchen. Wiederhole eine idempotente Operation mit demselben Schlüssel und Body. Wiederhole Authentifizierungsfehler oder verweigerte Berechtigungen nicht blind. Kaufe nicht allein wegen eines Timeouts eine zweite Subscription. Erneuere Quote oder Draft nur, wenn die vorhandene Anweisung nicht mehr nutzbar ist.

Challenge und Token-Austausch sind auf 30 Aufrufe pro Minute je IP begrenzt. Auflade-Drafts, Abo-Käufe und Watch-Erstellung sind auf 10 pro Minute je Wallet begrenzt. Watch-PATCH/-DELETE erlaubt 60 pro Minute; Settings-PUT und Nachrichtenvorschau erlauben 30 pro Minute; Alarm-Export erlaubt 10 pro Stunde. Limits gelten vor Idempotency, auch für Replays. Bei nicht verfügbarem Redis wird eine begrenzte prozesslokale Rückfallebene verwendet; Security-Limits lehnen bei ausgeschöpfter Rückfallkapazität ab.

Empfänger-Erstellung und Zieländerungen teilen sich 10 Aufrufe pro Stunde je Wallet. Bestätigungsmails haben Budgets je Wallet und kanonischem Ziel. Ein gedrosselter Neuversand kann HTTP 200 mit sent: false statt 429 liefern; prüfe dieses Feld. Eine Empfänger-Erstellung kann confirmationSent: false melden. Ein ausstehendes Ziel bleibt unverifiziert und darf keine Tests oder Alarme erhalten.

Konten-Ledger und Watch-Liste akzeptieren limit und einen undurchsichtigen cursor. Folge nextCursor bis null; interpretiere oder verändere den Cursor nicht. Alarm-Verlauf verwendet stattdessen nullbasierte page und pageSize mit Filtern und Sortierung. Der Export ist auf 5.000 Zeilen begrenzt. Vermische die beiden Paginierungsmodelle nicht.

curl 'https://ftso.app/api/x402/watches?limit=20' \
  -H 'authorization: Bearer fbx_READ_TOKEN'
# Follow the returned nextCursor, URL-encoded, on the next request.

Die vollständige Aufzählung stabiler Codes steht im OpenAPI-Dokument. Berechtigungen beschreibt die Referenz der Operationen.