Waafir
Diese Seite ist eine maschinelle Übersetzung, die noch auf eine menschliche Prüfung wartet. Sie kann Fehler enthalten.

Sicher mit einem Idempotenzschlüssel wiederholen

Dieses Rezept zeigt, wie Sie den Aufruf zum Starten eines Imports nach einem Netzwerkfehler oder einem uneindeutigen Fehler sicher wiederholen. Der Header Idempotency-Key bei POST /api/v1/monitoring/loan/imports sorgt dafür, dass der zweite Aufruf dieselbe Import-ID wie der erste zurückgibt, mit einer neu erzeugten Upload-URL – es wird kein doppelter Import angelegt.

Wann Sie dies verwenden

Immer dann, wenn Sie nicht feststellen können, ob der vorherige Aufruf zum Starten eines Imports angekommen ist. Die beiden typischen Fälle:

  • Ihr HTTP-Client hat eine Zeitüberschreitung gemeldet, bevor die Antwort eintraf. Die Anfrage hat Waafir möglicherweise erreicht und einen Import gestartet; Sie wissen es nicht.
  • Sie haben von einer nicht idempotenten Schnittstelle einen 5xx-Fehler erhalten und möchten wiederholen, ohne doppelte Arbeit zu riskieren.

Die plattformweite Konvention lautet, dass jeder verändernde Endpunkt Idempotency-Key akzeptiert – hier der Endpunkt zum Starten eines Imports, der Export-Endpunkt und an anderer Stelle die Endpunkte für Audit-Änderungen. Verwenden Sie pro logischem Vorgang einen neuen Schlüssel; verwenden Sie ihn bei Wiederholungen desselben Vorgangs erneut. Ein gängiges Muster ist eine UUID v4, die einmal pro Vorhaben „daily-import-batch“ erzeugt und in Ihrem Job-Status gehalten wird, bis der Aufruf erfolgreich ist.

Der Vertrag

  • Der Header lautet Idempotency-Key: <your-string>. Maximal 255 Zeichen.
  • Der Body akzeptiert auch ein Feld idempotencyKey; sind beide vorhanden, hat der Header Vorrang. Bevorzugen Sie den Header – er ist die maßgebliche plattformweite Platzierung.
  • Ein wiederholter Aufruf mit demselben (orgId, idempotencyKey) gibt Folgendes zurück:
    • dieselbe importId,
    • reused: true in der Antwort,
    • eine neu erzeugte Upload-URL (die ursprüngliche URL läuft ab; die neue ist die sicher verwendbare).
  • Ein wiederholter Aufruf mit einem anderen Body, aber demselben Schlüssel wird abgelehnt; der Schlüssel ist an die Struktur der ursprünglichen Anfrage gebunden.

Das Rezept

# curl — start an import with an idempotency key, then retry safely
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-2026-05-22.ndjson"
# Generate a fresh key per logical batch intent; keep it stable across retries.
IDEMPOTENCY_KEY="loan-import-2026-05-22-$(uuidgen)"

start_import() {
  curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports" \
    -H "Authorization: Bearer ${PAT}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    -d "$(cat <<JSON
{
  "kind": "loan",
  "filename": "${NDJSON_FILE}",
  "sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)"
}

# First call. If the network bombs out we have no idea whether the
# request landed — but the same key on the next attempt guarantees no
# duplicate import.
RESULT=$(start_import || true)

if [ -z "${RESULT}" ] || ! echo "${RESULT}" | jq -e .importId > /dev/null; then
  echo "first call ambiguous; retrying with the same idempotency key…"
  RESULT=$(start_import)
fi

echo "${RESULT}" | jq '{importId, reused, uploadUrl}'
# On a retry, reused == true; the importId matches the first call's; the
# uploadUrl is fresh.
// TypeScript — retry start-import safely with an Idempotency-Key
import { randomUUID } from "node:crypto";
import { statSync } from "node:fs";

const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-2026-05-22.ndjson";
const idempotencyKey = `loan-import-2026-05-22-${randomUUID()}`;

async function startImport() {
    return fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${PAT}`,
            "Content-Type": "application/json",
            "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify({
            kind: "loan",
            filename: NDJSON_FILE,
            sizeBytes: statSync(NDJSON_FILE).size,
        }),
    });
}

// Retry up to 3 times on transient failures; the same key makes this safe.
let lastError: unknown;
let result: { importId: string; reused: boolean; uploadUrl: string } | null = null;
for (let attempt = 1; attempt <= 3; attempt++) {
    try {
        const res = await startImport();
        if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
        result = (await res.json()) as typeof result;
        break;
    } catch (err) {
        lastError = err;
        console.warn(`attempt ${attempt} failed; retrying with same idempotency key`, err);
        await new Promise((r) => setTimeout(r, 1_000 * attempt));
    }
}

if (!result) throw lastError;
console.log({ importId: result.importId, reused: result.reused, uploadUrl: result.uploadUrl });
# python — retry start-import safely with an Idempotency-Key
import os
import uuid
import time
import requests
from pathlib import Path

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-2026-05-22.ndjson")

idempotency_key = f"loan-import-2026-05-22-{uuid.uuid4()}"

def start_import():
    return requests.post(
        f"{BASE_URL}/api/v1/monitoring/loan/imports",
        headers={
            "Authorization": f"Bearer {PAT}",
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "kind": "loan",
            "filename": NDJSON_FILE.name,
            "sizeBytes": NDJSON_FILE.stat().st_size,
        },
        timeout=30,
    )

# Retry up to 3 times on transient errors. The same key makes a second
# successful call a guaranteed replay of the first.
last_exc = None
result = None
for attempt in range(1, 4):
    try:
        response = start_import()
        response.raise_for_status()
        result = response.json()
        break
    except requests.RequestException as exc:
        last_exc = exc
        print(f"attempt {attempt} failed; retrying with same idempotency key: {exc}")
        time.sleep(attempt)

if result is None:
    raise RuntimeError("all retries exhausted") from last_exc

print({
    "importId": result["importId"],
    "reused": result["reused"],
    "uploadUrl": result["uploadUrl"],
})

Was Sie überprüfen sollten

Bei einem erfolgreichen ersten Aufruf ist reused gleich false. Bei jedem weiteren Aufruf mit demselben Schlüssel ist reused gleich true, und importId entspricht der des ersten Aufrufs. Die uploadUrl wird bei jedem Aufruf neu erzeugt, sodass eine Wiederholung nach Ablauf einer veralteten URL sicher ist – verwenden Sie immer die URL aus der jüngsten Antwort.

Wenn Sie mit einem anderen Anfrage-Body und demselben Schlüssel wiederholen, gibt die API einen Fehler zurück, der anzeigt, dass der Schlüssel an eine abweichende Anfragestruktur gebunden ist; verwenden Sie für das neue Vorhaben einen neuen Schlüssel.