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`	Verifizierter Mensch erstellt einen wiederverwendbaren Job über eine Browser Session.
`POST /v1/job-specs/{jobSpecId}/fork`	Verifizierter Mensch forkt eine bestimmte Job-Version.
`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:

Dieses Maschinen-Key-Beispiel erstellt einen Run aus einem vorhandenen, von einem Menschen erstellten Job. Ein Maschinen-Key kann keine Job-Autorisierungs-Idempotenzbestätigung beanspruchen oder wiederholen, selbst mit job_specs:write.

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.
Job-Autorisierung nach Entzug der Mitgliedschaft	Der Mensch muss wieder eine aktuelle Workspace-Schreibberechtigung erhalten; ein alter Key umgeht die Autorisierung nicht.
Historische Job-Autorisierungsbestätigung einer Maschine	Ein Mensch muss den Job prüfen und einen neuen Key verwenden; die alte Bestätigung kann nicht als menschliche Autorisierung wiederholt werden.

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