Guide: Idempotent publishing

Goal

Ensure publish requests are safe to retry without creating duplicate messages.

Prerequisites

• API key with messages:write
• You can publish messages (see Publish a message)

Steps

1) Always send Idempotency-Key on publish

If the client times out after the server accepted the request, retrying without idempotency would create duplicates.

curl -sS -X POST "$IRON_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $IRON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8742-charge" \
  -d '{"type":"order.charge","data":{"order_id":8742}}'

2) Reuse the same key for retries

Use the same Idempotency-Key for the same logical operation.

3) Set a reasonable retry policy

Retry transient errors with backoff. See Troubleshooting.

Validation

• Multiple retries return the same message ID (or the same effective result) for the same idempotency key.

Next steps

• Understand error codes: Error types

---

Next: Getting Started · Reference · Changelog · Support