Idempotenz | everyn

Wie Everyn-Clients Create-Requests sicher wiederholen, ohne Produktarbeit zu duplizieren.

Idempotenz verhindert, dass Netzwerk-Retries doppelte Datasets, Job Specs, Runs, Exports, Alert Rules, Webhook Endpoints, Organisationen, API Keys oder Einladungen erzeugen. Everyn behandelt den Idempotency Key als Teil des Create-Operation-Vertrags.

Idempotency-Regeln

Create-Routen, die Idempotency-Key verlangen:

Route	Zweck
`POST /v1/dataset-uploads`	Dataset-Upload-Session erstellen und Intake starten.
`POST /v1/job-specs`	Wiederverwendbaren Job Spec erstellen.
`POST /v1/runs`	Run aus Dataset und Job Spec erstellen.
`POST /v1/runs/{runId}/retry`	Retry Run mit Lineage erstellen.
`POST /v1/runs/{runId}/exports`	Self-starting Export erstellen.
`POST /v1/webhook-endpoints`	Webhook Endpoint erstellen.
`POST /v1/alert-rules`	Alert Rule erstellen.
`POST /v1/organizations`	Organisation über die Admin API erstellen.
`POST /v1/organizations/{organizationId}/api-keys`	Organisationsgebundenen API Key erstellen.
`POST /v1/organizations/{organizationId}/invitations`	Organisationseinladung erstellen.

Beispiel:

curl -sS -X POST "$EVERYN_BASE_URL/v1/runs" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: run-preview-20260707-leads-v1" \
  -H "Content-Type: application/json" \
  --data '{
    "datasetId": "ds_...",
    "jobSpecId": "js_...",
    "scope": { "type": "limit", "count": 25 }
  }'

Recovery-Regeln:

Situation	Client-Verhalten
Timeout vor Response	Denselben Request mit demselben `Idempotency-Key` wiederholen.
Gleicher Key, gleicher Body	Dieselbe logische Operation erwarten, keine doppelte Produktarbeit.
Gleicher Key, geänderter Body	`409 idempotency_conflict` erwarten; neuen Key nur für eine wirklich neue Operation wählen.
Neuer Run oder Retry ist beabsichtigt	Neuen Idempotency Key erzeugen und Retry oder Follow-up Run explizit machen.

Siehe den API Quickstart für Run-Erstellung und API-Fehler für 409-Recovery.