Idempotency and retries

Retry safety is narrower than most clients assume. This page lists exactly what the platform guarantees today; anything not listed is not idempotent.

The Idempotency-Key header

Fact	Value
Where it is honoured	Every write under /api/v1/ (POST/PATCH/PUT/DELETE) — a replay cache at the HTTP layer; POST /api/v1/tasks and POST /api/v1/tickets also store the key on the created record
Format	Any UUID, one per logical request
Window	24 hours: a retry with the same key returns the original response instead of creating a second object
Same key, different body	422 with code: "idempotency_conflict" and detail: "Idempotency-Key conflict: same key used with different request body" — the key is bound to the first body
What is replayed	2xx and 4xx answers; a 5xx is never cached, so a failed call can be retried with the same key. The replayed answer carries idempotent-replayed: true
In the contract	Declared as an optional header parameter on every write operation in openapi.json

curl -sS -X POST https://entherium.duckdns.org:8443/api/v1/tasks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1a6c62-0b5e-4d0f-9d1e-1f6a3b2c4d5e" \
  -d '{"title": "Re-check the source feeds of contract 42"}'

Naturally idempotent operations

Operation	Why repeating is safe
Every GET	Reads have no side effects
Defect / suggestion reports (POST /api/v1/tickets, MCP entherium_report_defect, entherium_propose_improvement)	Intake de-duplicates by content fingerprint: a repeated report is folded into the existing ticket, not filed twice — on top of the header
MCP entherium_target_task_spec, entherium_reassign_task	Setting the same target twice leaves the same state (idempotentHint: true)
PATCH that sets a field to the value it already has	A no-op by construction; status transitions are the exception below

Not idempotent — read the state first

Operation	What repeating does
entherium_update_task_status / ticket resolve · dismiss · reopen	The second call hits a state that no longer allows the transition → 409 illegal transition. Re-read before deciding
entherium_log_task_note	Appends a second note
Run launches (POST /api/v1/runs/…)	Starts another run; check the run list before retrying a launch whose response you lost
Agent writes to entities	Applied each time; a lost response does not mean a lost write — read back before repeating

How to retry, by error class

You got	Retry?	How
Network timeout / connection reset	Yes, for reads and for the two intake endpoints with the same Idempotency-Key; for other writes read back first	Exponential backoff from 1 s, at most 5 attempts
429	Yes	Wait the Retry-After seconds, then repeat the same request
500	Once	Short pause, then file a defect quoting request_id if it repeats
502 / 503 / 504	Yes, slowly	The platform is down, paused or not ready — poll status rather than hammering
Any other 4xx	No	The request is wrong; detail and doc_url say what to fix (Errors)

MCP: what the hints promise

Every tool declares idempotentHint and readOnlyHint (tools reference). readOnlyHint: true tools can be repeated freely. A write tool with idempotentHint: true may be repeated with the same arguments; one with idempotentHint: false must not be repeated without reading the object first. The hints are derived from the same code that runs the tools, so they cannot be out of date relative to the server you are connected to.