---
icon: shield
title: Fehler und Idempotenz
description: 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

```mermaid
flowchart TD
  Request[API Anfrage] --> Ok{Erfolg}
  Ok -->|yes| Data[data und meta]
  Ok -->|no| Problem[problem plus json]
  Problem --> Code[Stabiler Top Level Code]
  Request --> Write{Schreiben}
  Write -->|POST create| Idem[Idempotency Key]
  Write -->|PATCH PUT DELETE| ETag[If Match ETag]
```

Lesen Sie dies zusammen mit der Zusammenfassung in der [Übersicht](/docs/de/api/overview), [Authentifizierung](/docs/de/api/authentication) für `401`-Fälle und [Rezepten](/docs/de/api/recipes) 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:

```json
{
  "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.

```http
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
```

```bash
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.

:::tip
Erzeugen Sie eine neue UUID **pro logischem Create**. Verwenden Sie denselben Schlüssel nur, wenn Sie denselben **beabsichtigten** Create nach einem Netzwerkfehler erneut versuchen. Verwenden Sie einen Schlüssel nicht für einen anderen Payload erneut.
:::

## Optimistic Concurrency (ETag)

`GET`s 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 |

```http
GET /api/v4/users/usr_123 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

Die Antwort enthält:

```http
ETag: "abc123version"
```

Dann:

```http
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
```

```bash
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 `400`s** — Anfrage korrigieren; Retries ohne Änderung scheitern weiter.

:::warning[Im Budget bleiben]
Eine enge Paginierungsschleife mit `limit=1` kann das Budget von 1000/min schnell verbrauchen. Bevorzugen Sie größere Seiten und Backoff, wenn `RateLimit-*`-Header gegen null Remaining gehen.
:::

## 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

**[Rezepte](/docs/de/api/recipes)**

Sichere Updates und idempotente Create-Walkthroughs.

**[Paginierung und Filterung](/docs/de/api/pagination-and-filtering)**

invalid_cursor und effiziente Listendurchläufe.

**[Authentifizierung](/docs/de/api/authentication)**

401 und Umgang mit Zugangsdaten.

**[API-Übersicht](/docs/de/api/overview)**

Konventionsübersicht und Migrationshinweise.
