---
title: "Safe retries"
description: "Retry a request without doing it twice."
url: "https://docs.goomzo.africa/docs/developers/idempotency"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Overview"
related:
  - /docs/developers
  - /docs/developers/authentication
  - /docs/developers/rate-limits
  - /docs/developers/errors
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# 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.

```bash
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.

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)