Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

Fehler und Idempotenz

RFC 7807 Problem Details, Idempotency-Key, ETag-Optimistic Concurrency und Rate Limits für die Fuxam API v4.

Wenn etwas schiefgeht — oder wenn Sie absichtlich erneut versuchen — folgt die Fuxam API v4 einem kleinen Satz strenger Regeln: RFC 7807-Problemdokumente für Fehler, Idempotency-Key für sichere Creates, ETag / If-Match für sichere Updates und Deletes sowie RateLimit-* / Retry-After, wenn Sie das gemeinsame Budget erreichen. Einmal gelernt, machen diese Regeln jeden Endpunkt sicherer zu automatisieren.

Warum das wichtig ist

Integrationen scheitern in der Praxis: Netzwerke brechen mitten im POST ab, zwei Jobs aktualisieren denselben Nutzer, eine Sync-Schleife überschreitet 1000 Anfragen pro Minute. Ohne Idempotenz und Concurrency-Kontrolle riskieren Sie doppelte Datensätze oder stille Überschreibungen. Ohne stabilen Fehler-code können Sie in Client-Code nicht zuverlässig verzweigen. Dieses Kapitel ist der Vertrag für diese Fehlermodi.

Wie es zusammenhängt

Lesen Sie dies zusammen mit der Zusammenfassung in der Übersicht, Authentifizierung für 401-Fälle und Rezepten für kopierfertige Muster.

Schlüsselkonzepte

Konzept Bedeutung
Problem details RFC-7807-JSON-Body mit Content-Type: application/problem+json.
ApiErrorCode Geschlossene Menge stabiler Top-Level-code-Werte (zum Beispiel resource_not_found).
Zod issue code Feldbezogene Validierungscodes in errors[] (zum Beispiel invalid_string) mit RFC-6901-Pointern.
Idempotency-Key Vom Client erzeugter Schlüssel, der ein Create-POST innerhalb des Idempotenzfensters wiederspielsicher macht.
ETag / If-Match Optimistic Concurrency: Schreiben nur, wenn die Ressourcenversion noch übereinstimmt.
Rate limit 1000 Anfragen/min pro Integration + Institution (gleitendes Fenster).

Fehlermodell (RFC 7807)

Alle Fehler verwenden application/problem+json. Das Feld type ist die URI https://fuxam.app/errors/{code}.

Es gibt zwei getrennte code-Namespaces:

Namespace Wo Zweck
Top-Level-code Wurzel des Problemdokuments Geschlossene ApiErrorCode-Union — maschinenlesbar und über Client-Versionen hinweg stabil
errors[].code Optionale Array-Einträge Zod-Issue-Codes (zum Beispiel invalid_string) mit einem RFC-6901-pointer (zum Beispiel /email)

Beispiel:

{
  "type": "https://fuxam.app/errors/resource_not_found",
  "title": "Not Found",
  "status": 404,
  "code": "resource_not_found"
}

Kein 403 — Privatsphäre durch Uniformität

v4 sendet kein 403. Cross-Tenant-Zugriff liefert dasselbe 404 resource_not_found wie eine wirklich fehlende Ressource. Die Existenz von IDs einer anderen Institution wird nie preisgegeben. Client-Code sollte 404 als „für Sie nicht verfügbar“ behandeln, nicht nur als „hat nie existiert“.

Validierungsfehler liefern HTTP 422.

Häufige Statuscodes

Status Typische Bedeutung
200 Erfolgreiches Lesen oder Aktualisieren
201 Ressource erstellt
204 Ressource gelöscht (kein Body)
400 Ungültige Anfrage (zum Beispiel invalid_cursor)
401 Authentifizierung fehlgeschlagen
404 Fehlende Ressource oder Cross-Tenant-Ablehnung (resource_not_found)
409 Konflikt oder laufender Idempotenz-Lock
412 ETag-Mismatch (precondition_failed)
422 Validierungsfehler
428 Erforderliches If-Match fehlt (precondition_required)
429 Rate Limit überschritten — Retry-After beachten

Idempotenz für Creates

POST-Anfragen, die Ressourcen erstellen, akzeptieren einen Idempotency-Key-Header. Das erneute Senden desselben Schlüssels innerhalb des Idempotenzfensters liefert die zwischengespeicherte Antwort (einschließlich des ursprünglichen 201) zurück, ohne ein Duplikat zu erzeugen. Konfliktierende laufende Schlüssel können 409 zurückgeben.

POST /api/v4/users HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Accept: application/json
IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d @create-body.json \
  "https://fuxam.app/api/v4/users"

Verwenden Sie den JSON-Body, der in der Endpunktreferenz der Create-Operation dokumentiert ist — der wichtige Teil dieses Musters ist die Wiederverwendung desselben Idempotency-Key bei Retries.

Optimistic Concurrency (ETag)

GETs auf Einzelressourcen senden ein starkes ETag. Senden Sie es als If-Match bei PATCH, PUT oder DELETE zurück:

Ergebnis Status / Code Bedeutung
Version noch aktuell Erfolg (200 / 204) Schreibvorgang angewendet
Ressource seit dem Lesen geändert 412 precondition_failed Erneut GET, mergen, mit neuem ETag erneut versuchen
If-Match erforderlich, aber fehlend 428 precondition_required If-Match mitsenden
GET /api/v4/users/usr_123 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json

Die Antwort enthält:

ETag: "abc123version"

Dann:

PATCH /api/v4/users/usr_123 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
If-Match: "abc123version"
Accept: application/json
ETAG='"abc123version"'

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${ETAG}" \
  -d @patch-body.json \
  "https://fuxam.app/api/v4/users/usr_123"

Legen Sie die Felder, die Sie ändern möchten, gemäß Endpunktreferenz in patch-body.json ab; koppeln Sie den Schreibvorgang stets mit dem soeben gelesenen ETag.

Rate Limits

Jede Integration teilt sich ein Budget von 1000 Anfragen/min (gleitendes Fenster, Schlüssel aus Integration + Institution). Antworten enthalten RateLimit-*-Header. Wenn Sie das Budget überschreiten:

  • Status: 429
  • Header: Retry-After (beachten Sie ihn vor dem erneuten Versuch)

Retry- und Backoff-Empfehlungen

Behandeln Sie Retries als gestufte Richtlinie:

  1. 429 — warten Sie Retry-After Sekunden (oder die von Ihrem Client geparste vorgeschlagene Verzögerung), dann dieselbe Anfrage erneut versuchen.
  2. Transiente Netzwerkfehler bei sicheren Reads — mit exponentiellem Backoff und Jitter erneut versuchen.
  3. Transiente Fehler bei Creates — mit dem selben Idempotency-Key erneut versuchen.
  4. 412 bei Writes — denselben Body nicht blind mit dem alten ETag erneut senden; erneut lesen, abgleichen, neues If-Match senden.
  5. 422 / 401 / die meisten 400s — Anfrage korrigieren; Retries ohne Änderung scheitern weiter.

Best Practices

  • Verzweigen Sie auf dem Top-Level-code, nicht nur auf dem menschenlesbaren title-Text.
  • Stellen Sie meta.requestId aus erfolgreichen Aufrufen und alle in Problemdokumenten zurückgegebenen Kennungen bereit, wenn Sie Fehler loggen.
  • Senden Sie bei automatisierten Create-Jobs stets Idempotency-Key.
  • Senden Sie bei Einzelressourcen-Writes, die es erfordern, stets If-Match.
  • Mappen Sie 404 in UI oder Sync-Logik auf einen einzigen „nicht verfügbar“-Pfad — speziellen Sie keinen fiktiven 403.

Häufige Fallstricke

Fallstrick Folge Lösung
POST ohne Idempotency-Key erneut versuchen Doppelte Ressourcen Pro logischem Create einen Schlüssel erzeugen und wiederverwenden
412 ignorieren Überschreibungsrennen oder endlose Retries Erneut GET und mergen
404 immer als „aus lokalem Cache löschen“ behandeln Kann Berechtigungs-/Tenant-Probleme verdecken Zuerst mit einer bekannten gültigen ID bestätigen
Busy-Loop bei 429 Längerer Lockout, verschwendete Rechenzeit Retry-After beachten

FAQ

Was ist der Unterschied zwischen den beiden code-Feldern?

Der Top-Level-code ist die stabile API-Fehlerklassifikation. Einträge in errors[].code beschreiben einzelne Validierungsprobleme (Zod) und enthalten einen pointer auf das fehlschlagende Feld.

Werde ich jemals HTTP 403 sehen?

Nicht über den Cross-Tenant-Ablehnungspfad von v4 — das ist absichtlich 404. Gestalten Sie Clients entsprechend.

Wie lange ist das Idempotenzfenster?

Die Übersicht dokumentiert, dass Wiedergaben innerhalb des Idempotenzfensters die zwischengespeicherte Antwort zurückgeben. Behandeln Sie den Schlüssel als für sinnvolle Retry-Zeiträume gültig; verlassen Sie sich nicht dauerhaft auf Schlüssel — verwenden Sie für ein neues logisches Create einen neuen Schlüssel.

Verwandte Seiten

War diese Seite hilfreich?