Retry the operation, not the accident
An idempotency key identifies one intended message operation. HTTP attempts may repeat; the business operation should not.
Required format
Idempotency-Key is required for POST /v1/messages. It must be 8–128 characters using letters, digits, underscore, period, colon, or hyphen.
Idempotency-Key: checkout:order-8472:shipped:v1
Choose a stable key
Build the key from a durable business identifier and event version. Good keys survive process restarts and are available before the HTTP call. Avoid random per-attempt UUIDs because they turn every retry into a new accepted operation.
- Good:
invoice:inv-1048:payment-due:v2 - Good:
auth:challenge-93:attempt-1 - Bad: current timestamp generated inside each retry loop
- Bad: recipient phone number or other personal data
What MessageHop binds
The idempotency identity is scoped to the Organization, Registered App, v1 message operation, and key. MessageHop also hashes the material request: Project, App, channel, destination, template, sorted variables, and client reference.
Replay outcomes
- Same key, same material: the original accepted record and message identity are returned; a duplicate queue or billing reservation is not created.
- Same key, different material: the API returns
409 idempotency_conflict. Do not retry with the same key until the caller's state is reconciled. - Timeout with unknown response: send the exact request again with the exact key.
Caller persistence
Store business event ID, idempotency key, canonical request hash or material, MessageHop message ID, request ID, first-attempt time, and latest known state. Use an outbox in your own database if message submission follows a customer transaction.
Retries after acceptance
Do not create a new API request simply because provider delivery is delayed. MessageHop owns bounded provider dispatch and its state evidence after durable acceptance. A second customer-visible message should be a new, intentional business operation with its own key and policy.