Skip to main content
Network calls fail in ways that leave you unsure whether the request went through. Idempotency keys make retries safe: replay the same request with the same key and MADIAD Hub returns the original result instead of publishing again.

​
Send an idempotency key

Add an Idempotency-Key header with a value you control — a UUID per logical action is ideal. The Hub also accepts X-Idempotency-Key or X-Request-Id as equivalents.

​
How it behaves

  • First request with a key — processed normally; the result is stored against that key.
  • Replay with the same key and the same content — returns the stored result; no second post is created, and the response carries Idempotent-Replayed: true.
  • Same key, different content — rejected with 409 idempotency_conflict. Nothing is published.
  • Different key — treated as a brand-new request.
Generate the key before the first attempt and reuse it for every retry of that same action. Generating a new key on retry defeats the purpose.

​
Telling a replay apart from a fresh publish

A replayed response is identical to the original — same request_id, same status. That is the point, but it means an automation whose key stops changing keeps receiving successful-looking responses while nothing new is being published. Every replayed response therefore carries a header:
A fresh publish never sets it. If you run scheduled or queued publishing, treat this header as an alarm: it means the key you sent had already been used, so the content you just submitted did not go out.
Use a new key for every new post. A counter that stops advancing, a retried workflow item, or a template that hardcodes the key will all send content under a key that is already spoken for. Since 26 July 2026 that returns 409 idempotency_conflict when the content differs — before then it silently returned the earlier result.

​
When the outcome is unknown

A publish can take longer than MADIAD Hub is allowed to wait. When that happens the request is not reported as a failure, because the post may well have gone out — we stopped waiting, the platform did not stop working. You get 502 with code upstream_timeout, nothing is refunded, and the key you sent is closed against that answer. Replaying it returns the same 502 and the same body — deliberately, so an automation branching on the status code cannot record an unknown post as a success.
What to do:
  1. Check history or the platform itself before doing anything else.
  2. If it did not publish, send it again with a new Idempotency-Key — the old one now permanently answers “unknown”.
  3. Never retry it automatically on the same key expecting a different result.

​
When to use it

Always, for any request that creates something — posts in particular. It’s essential when:
  • A client or workflow tool (n8n, queues, cron) auto-retries on timeout.
  • A webhook or job may be delivered more than once.
  • A user double-clicks publish.
Keys are scoped to your account and remembered long enough to cover realistic retry windows.