​

Idempotency

​

When to use

• Scheduled jobs. Cron fires at 9am Monday. Use idempotency_key: "weekly-deck:2026-W17". If your worker crashes after the POST succeeds but before writing the response, the next retry returns the same task.
• Network-timeout retries. Your HTTP client times out mid-POST. Retry with the same key — safe.
• Upstream-triggered flows. A Slack command fires two webhooks on the same action. Use the slack message ID as the key: idempotency_key: "slack:T01234:123456.789".
• Bulk fan-out. 50 prospects × one task each. idempotency_key: "prospect:{id}:2026-04-weekly" keeps re-runs safe.

​

How it works

POST /v1/tasks
{ "prompt": "…", "idempotency_key": "focustime-v1", ... }

• First call: creates the task, returns the envelope.
• Second call with the same key: returns the original task’s envelope. The task lane matches on the key alone — it does not compare request bodies, so a reused key with a different prompt silently replays the first task rather than starting the new one.

​

Key design

• Stable and unique per logical operation. “weekly-deck” alone is bad (reused every week); "weekly-deck:2026-W17" is good.
• Hash complex inputs if the key would otherwise be long: sha256(prompt + brand_kit_id + format). Deterministic + short.
• Namespace per integration — keys are not isolated per API key. The task lane looks a key up globally, and the hashed lanes scope records to (team, user, operation, key). Two of your integrations sharing a team can collide on a bare "weekly-deck" and silently replay each other’s result. Prefix them: "myapp:weekly-deck:2026-W17".
• TTL. Idempotency records are retained long enough to cover sensible retry windows (24h on the hashed lanes) — don’t build around a specific duration. If you’re retrying a week later, use a different key.

​

Beyond POST /v1/tasks

​

Conflict handling (hashed lanes)

{
  "error": {
    "type": "conflict",
    "code": "idempotency_conflict",
    "message": "An existing operation is associated with this idempotency_key but with a different request body.",
    "request_id": "019d8996-…"
  }
}

• Use a different idempotency_key for the new body.
• Change your code so the body is byte-identical (e.g. canonicalize array order, don’t include a timestamp in the payload).

​

Not wired (yet)

• Idempotency-Key HTTP header (Stripe-style). Today, idempotency_key is a body field. A header-based variant is on the roadmap; when it lands, existing body-field usage continues to work.

​

Webhook idempotency (separate concern)

​

Worked example — weekly cron

iso_week = datetime.utcnow().strftime("%Y-W%V")                 # e.g. "2026-W17"
resp = httpx.post(
    "https://api.moda.app/v1/tasks",
    headers=HEADERS,
    json={
        "prompt": build_weekly_prompt(),
        "format": {"category": "slides", "width": 1920, "height": 1080},
        "number_of_slides": 10,
        "callback_url": "https://myapp.com/webhooks/moda",
        "idempotency_key": f"weekly-deck:{iso_week}",
    },
)
# safe to retry this whole call on network error — same key, same body

​

Common wrong guesses

• Using an Idempotency-Key HTTP header. Not supported today. Use the body field idempotency_key.
• Reusing the same key across different operations. “default” as the key for every task. You’ll just keep getting back the first task you ever created with that key.
• Changing the body and reusing the key on POST /v1/tasks. You get the old task back, not an error and not a new task — the task lane never compares bodies. Use a fresh key when the intent changed. (On the hashed lanes below, the same mistake is a loud 409 idempotency_conflict.)
• Assuming idempotency_key is task-only. POST /v1/brand-kits and the metered verbs take it too, with the same replay / 409 semantics. Check the endpoint’s request schema.

​

Upstream

• docs.moda.app/api/tasks/startTask — parameter reference
• errors.md — the full error envelope including idempotency_conflict