Why
If a create call times out, you do not know whether the task exists. Sending the same call again with the same Idempotency-Key is safe: it returns the original task and does not charge twice.
The rules
- Required.
POST /v1/taskswithout anIdempotency-Keyheader is400 invalid_request, withparamset toIdempotency-Key. The samples add one to every task creation. The packages are not published yet, so a hand-written call has to send the header itself. - A string of up to 128 characters. A new UUID for each new task is the simplest.
- Scoped to the API key. The same string sent with two keys of one account makes two tasks.
- A window of 24 hours from the first time Opsis accepted it.
- A replay is the same key with the same request. It returns the original task in its current status, with
202. No second task and no second charge.waitis ignored on a replay. - A conflict is the same key with a different request. It answers
409 idempotency_conflict. The request is compared bymodel,input,webhook_url,namespaceandretention_seconds.
A replay does not depend on anything else
Opsis reads the key first. If the key exists with the same request, it returns the original task and nothing else runs: not the account's state, not the pause switch and not the checks at create. So a replay never depends on Civitai being reachable or on your image link still existing.
Retrying
Retry only 429, 500 and 503, with backoff, and reuse the same key. See Errors. A retry that should be a new task needs a new key. Finish any retries before you revoke a key, since the scope is the key.
const key = crypto.randomUUID() // once for this task, kept for every retry
|
const task = await opsis.tasks.create(body, { idempotencyKey: key }) |