The following public endpoints accept an optional Idempotency-Key header for safe replay:
POST /v1/payments/topupPOST /v1/chat/completionsPOST /v1/embeddings
The key is applied after authentication, so it is scoped to the caller.
When to use a key
Use an idempotency key when the network fails after you have sent a request and you do not know whether the server completed it. The key lets you retry without creating a duplicate top-up, duplicate billed chat completion, or duplicate embedding request.
Idempotency-Key: 3e2a7b4e-5c38-4d7b-bf12-1a3f46d9f1a8Request lifecycle
| Situation | Result |
|---|---|
| First request with a new key | The request executes normally and its response is cached for 24 hours. |
| Retry with the same key while the first request is still running | Returns 409 idempotency_conflict; wait and retry again with the same key. |
| Retry with the same key after completion | Replays the original response and does not execute or charge again. The response includes Idempotency-Replayed: true. |
| Request without a key | Executes normally with no replay protection. |
Top-up example
/v1/payments/topupJWTcurl -X POST https://api.ngamia.cc/v1/payments/topup \\
-H "Authorization: Bearer $NGAMIA_ACCESS_TOKEN" \\
-H "Content-Type: application/json" \\
-H "Idempotency-Key: $(uuidgen)" \\
-d '{"amount_tzs": 5000}'The key determines the replay. Ngamia does not compare the request body. Generate a fresh key for every logical operation, and never reuse a key for a different top-up, chat, or embedding request. Raw-audio speech and voice response calls should not be treated as replay-safe unless your deployment explicitly documents that behavior.
Practical retry rule
Keep the key with the job or request record in your application. If the request times out, retry the same logical operation with the same key. If you intentionally start a new operation, generate a new UUID.
These operations are protected because a dropped connection can otherwise create a duplicate financial action or duplicate billed gateway work. Other read and update operations can generally be retried using their normal request semantics. See Voice & Ongea na Ngamia for media retry cautions.