Idempotency & retries
Retry the same request without accidentally creating a new operation.
Give each write a stable identity
Mutating POST requests require an Idempotency-Key between 8 and 200 characters. Generate it once per intended operation and retain it across retries. Use a new key for a genuinely new operation.
Idempotency-Key: 451fa6b8-7e47-43e5-8fd1-72f18cd2a630The key is bound to the request
The stored identity includes the operation, target and body. Repeating the same request replays its recorded response. Reusing the key for different contents or a different target returns a conflict. Authorization is checked again before replay.
Keep the message identity too
Message submission also has a client_message_id. Keep both that UUID and the Idempotency-Key when retrying a message. Neither identifier proves that an external business action occurred.
Retry with care
On a network timeout, retry the same request identity with bounded backoff. Inspect a 409 before retrying: it may be a changed request or stale state. Respect Retry-After when provided. Do not blindly repeat business actions whose outcome is unknown.
Need a hand? Get in touch