Retries and idempotency. Safe to retry, charged once.
Networks fail. Send an Idempotency-Key with a POST and a retry returns the first result instead of doing the work again.
First try201 Created
Idempotency-Key: order-1001-q1Retry after a timeoutReplayed
Idempotency-Key: order-1001-q1 One message, charged once
On this page
How it works
- Send
Idempotency-Key: <a unique string>(up to 255 characters, a UUID is ideal) withPOST …/messagesorPOST …/replies. - Retry with the same key and the same body within 24 hours and you get the first response again, with the header
Idempotent-Replayed: true. No second message is sent and nothing is charged twice. - Generate a new key for each new message, and reuse it only for retries of that message.
Conflicts
| Status | Code | When |
|---|---|---|
| 409 | idempotency_in_progress | The first request with this key is still running. Wait a moment and retry. |
| 409 | idempotency_key_reused | The key was used with a different body. Use a new key. |
Other requests are safe to retry as they are: reads change nothing, and a second take-over, resolve or delete returns a 409 or 404 you can treat as done.