# Idempotenz

> Senden Sie bei POST-Anfragen einen Idempotency-Key, damit eine wiederholte Anfrage eine Prüfung nie zweimal ausführt oder berechnet. Verhalten, erneut ausgelieferte Antworten und Konflikte.

Quelle: https://fileverity.com/de/docs/idempotency

Nach einem Netzwerkfehler wissen Sie unter Umständen nicht, ob eine POST-Anfrage angekommen ist. Wenn Sie sie einfach erneut senden, kann eine Prüfung zweimal ausgeführt und berechnet werden. Senden Sie einen Header `Idempotency-Key`, und die Wiederholung liefert stattdessen die erste Antwort zurück.

## Den Header verwenden

**Idempotente Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \
  -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'
```

**Idempotente Anfrage: JavaScript**

```javascript
async function createAnalysis(body) {
  const key = crypto.randomUUID();
  let lastError;
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await fetch("https://api.fileverity.com/v1/analyses", {
        method: "POST",
        headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key },
        body: JSON.stringify(body),
      });
    } catch (error) {
      lastError = error;
    }
  }
  throw lastError;
}
```

**Idempotente Anfrage: Python**

```python
import uuid

def create_analysis(body):
    key = str(uuid.uuid4())
    last_error = None
    for attempt in range(3):
        try:
            return requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body, timeout=90)
        except requests.ConnectionError as error:
            last_error = error
    raise last_error
```

- Senden Sie eine beliebige eindeutige Zeichenfolge mit 1 bis 255 Zeichen. Eine zufällige UUID eignet sich gut. Verwenden Sie für jede unterschiedliche Anfrage einen neuen Schlüssel und denselben Schlüssel nur, um dieselbe Anfrage zu wiederholen.
- Der Header funktioniert bei jedem POST-Endpunkt: `/text/detections`, `/files`, `/analyses` und `/analyses/{id}/cancel`.
- Idempotenzschlüssel gelten jeweils für Ihren Workspace, den Modus (Live oder Test) und den Endpunkt und werden 24 Stunden lang aufbewahrt. Derselbe Idempotenzschlüssel kollidiert nicht, wenn er mit einem Live- und einem Testschlüssel verwendet wird.

## Was Sie zurückerhalten

| Situation | Ergebnis |
| --- | --- |
| Erste Anfrage mit einem Idempotenzschlüssel | Wird normal verarbeitet. Erfolgreiche Antworten (Status unter 400) werden gespeichert. |
| Derselbe Schlüssel und derselbe Anfragetext innerhalb von 24 Stunden | Die gespeicherte Antwort mit demselben Status sowie dem Header `idempotent-replayed: true`. Es wird nichts erneut ausgeführt oder berechnet. |
| Derselbe Schlüssel, anderer Anfragetext | `409` `idempotency_mismatch`. |
| Derselbe Schlüssel, während die erste Anfrage noch läuft | `409` `idempotency_in_progress`. Versuchen Sie es in Kürze erneut. |
| Derselbe Schlüssel nach einer Fehlerantwort | Der Schlüssel wird freigegeben. Ein Fehler wird nicht gespeichert, daher führt eine Wiederholung die Anfrage erneut aus. |

Eine erneut ausgelieferte Antwort behält die `x-request-id` der neuen Anfrage, nicht die der ursprünglichen. Multipart-Uploads werden anhand ihrer Formularfelder und Dateiinhalte verglichen.

> **Hinweis.** Idempotenz vermeidet doppelte Arbeit. Sie sorgt nicht dafür, dass eine fehlgeschlagene Anfrage gelingt: Warten Sie nach `service_unavailable` oder `internal_error` die Sekunden aus `retry-after` ab, falls die Antwort diesen Header enthält, und wiederholen Sie die Anfrage dann mit demselben Idempotenzschlüssel.

Siehe auch [Fehler](https://fileverity.com/de/docs/errors.md) und [Rate-Limits und Header](https://fileverity.com/de/docs/rate-limits.md).