Pass an Idempotency-Key header (any string up to 255 characters, e.g. erp-2026-05-18-batch-1) on bulk-write requests. Mercura keys jobs on (organisation, Idempotency-Key):
- Same key + same body → the original
job_idis returned with200 OK. No second job runs. - Same key + different body →
422 IDEMPOTENCY_KEY_MISMATCH. This is almost always a bug on the caller side; we refuse to silently replay a different payload under a key you said you were reusing. - No header → every call is a new job.
This lets you safely retry on network or proxy failures without double-writing.
A replay returns the original job as it ended — a job that FAILED stays failed, however often you resend it. After fixing the cause (say, creating a missing tag), send the batch again under a new key. So build the key from the sync run, not from the payload alone: for example articles-<run id>-<batch number>, reused only when you retry that same request after a timeout, a dropped connection or a 5xx. A key derived purely from a content hash makes an unchanged file impossible to process a second time.