Safe retries
Retry a request without doing it twice.
If a request times out or the connection drops, you can't tell whether it was done. Retrying it could add a
customer twice or send a message twice. To retry safely, send an Idempotency-Key header.
curl https://api.goomzo.africa/v1/messages \
-H "Authorization: Bearer $GOOMZO_TOKEN" \
-H "Idempotency-Key: 6f1c2d3e-order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{"to": "0712345678", "channel": "sms", "body": "Your order is ready."}'The key can be any text up to 255 characters without spaces. A UUID, or an ID from your own system such as an order number, works well.
How it works
It works on any POST. The first request with a key is done as normal. For the next 24 hours, sending the same
request with the same key doesn't do it again: you get the first answer back, with the header
Idempotent-Replayed: true.
| When you send the same key... | You get |
|---|---|
| With the same request | The first answer again, without doing it twice |
| With a different request | 422 idempotency_key_reused. Use a new key. |
| While the first is still being answered | 409 idempotency_key_in_use. Wait a moment and retry. |
After the first failed on our side (5xx) | The request is done again, as if new |
Keys belong to each service account, so two systems can't clash by choosing the same key. Use a new key for each new thing you want done.