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:
429— warten SieRetry-AfterSekunden (oder die von Ihrem Client geparste vorgeschlagene Verzögerung), dann dieselbe Anfrage erneut versuchen.- Transiente Netzwerkfehler bei sicheren Reads — mit exponentiellem Backoff und Jitter erneut versuchen.
- Transiente Fehler bei Creates — mit dem selben
Idempotency-Keyerneut versuchen. 412bei Writes — denselben Body nicht blind mit dem alten ETag erneut senden; erneut lesen, abgleichen, neuesIf-Matchsenden.422/401/ die meisten400s — Anfrage korrigieren; Retries ohne Änderung scheitern weiter.
Best Practices
- Verzweigen Sie auf dem Top-Level-
code, nicht nur auf dem menschenlesbarentitle-Text. - Stellen Sie
meta.requestIdaus 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
404in UI oder Sync-Logik auf einen einzigen „nicht verfügbar“-Pfad — speziellen Sie keinen fiktiven403.
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.