Idempotency

Mutating requests that move money, allocate inventory, or trigger external
side-effects accept an Idempotency-Key header. Replays with the same
key return the original response and do not re-run the side-effect.

Endpoints that require an idempotency key are flagged with the
Idempotency-Key header in their reference page. Endpoints where it is
optional will gladly accept it too — it costs you nothing and protects
against retries.

How to generate keys

• Use a fresh UUIDv4 per logical operation.
• The same key for two different payloads returns
  409 IDEMPOTENCY_CONFLICT.
• Keys are scoped per (api-key, endpoint). Reusing a key on a different
  endpoint is allowed but discouraged.

Lifetime

Keys are remembered for 24 hours. Replay within that window returns the
cached response. After 24 hours the key is forgotten and the request will
execute again.

Example

curl https://api.megsapp.85.group/api/v1/wallets/{id}/topup \
  -X POST \
  -H 'x-api-key: …' \
  -H 'idempotency-key: 0c5b1ee0-…' \
  -d '{ "amountCents": 5000, "currency": "ZAR" }'

Replaying with the same Idempotency-Key:

• Same payload → original 200/201 response, no double-charge.
• Different payload → 409 IDEMPOTENCY_CONFLICT.

Errors and retries

If the original request returned a 5xx, the cached response is also a
5xx. To retry that operation safely, use a new idempotency key.