# Idempotency

`POST /v1/simc/jobs` accepts an optional `idempotency-key` header so retries return the original job rather than creating a duplicate. Use a UUID or request hash, up to 255 characters. Keys are scoped to the client (the API key making the request) and to this endpoint, so the same key on a different client or endpoint is independent.

## Replays

A replay returns the original response body with HTTP `200` and an `X-Idempotent-Replay: true` response header so you can distinguish it from a fresh insert. Replays count against your rate-limit budget. Wait for `Retry-After` rather than rotating keys to retry past the limit.

Keys remain valid for the lifetime of the underlying job. Replays still resolve after the job reaches a terminal status (`completed`, `failed`, `cancelled`, `timed_out`); the key is not freed when the job ends.

## Conflicts

If the same key is reused with a different request payload, the API responds with `409` and `code: "idempotency_key_reuse"`. The `meta.originalJobId` field returns the id of the job that originally consumed the key so you can poll its status if you've lost it locally.

## What counts as the same payload

The digest used to detect reuse covers the request body except `metadata`. `metadata` is opaque correlation data and is intended to be mutated across retry attempts (e.g. bumping a `retry_attempt` counter or rotating a `trace_id`). Every other field is part of the digest, including `bnetApiKey`. Rotate the idempotency key alongside any credentials you rotate.

---

_HTML version: https://simmit.com/docs/api-advanced/idempotency · Full docs index: https://simmit.com/llms.txt_