Technical note
Idempotency keys in telecom API design
If you sell telecom APIs, partners will retry. Networks glitch, client SDKs time out, and operations teams replay requests from scripts. Without idempotency, a harmless retry becomes a duplicate SIM order, a second number purchase, or a wallet debit that support has to unwind manually.
Start from partner-visible states
Model provisioning as state machines with explicit transitions. Your HTTP layer should accept an idempotency key on mutating endpoints and return the same final response when the key repeats, even if the upstream provider answered slowly the first time.
Separate your ledger from the provider
Store idempotency records in your database before you call upstream. If the provider accepts a request but your client disconnected, the retry must not create a second upstream operation. When providers lack native idempotency, your adapter must emulate it with stable correlation IDs and careful reconciliation jobs.
Retries need policy, not hope
Use bounded retries with jitter on transient errors only. Permanent provider errors should surface quickly with actionable codes. Background workers can continue long-running provisioning, but the API response should still be coherent: either a stable resource ID or a clear pending state partners can poll.
Observability
Log idempotency keys (hashed if needed), adapter latency, and provider error classes. When support asks why a partner sees duplicates, you should answer with traces, not guesses.