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 '{"messages": [{"to": "+255712345678", "channel": "sms", "content": {"text": "Your order is ready."}}]}'The key can be any text up to 255 characters without spaces. A request without the header, or with it empty, is done as normal, every time. 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 was refused (4xx) | The same error again. Fix the request and use a new key. |
After the first failed on our side (5xx) | The request is done again, as if new |
Idempotency keys belong to each API key, so two systems can't clash by choosing the same one. Use a new one for each new thing you want done.
Last updated