Idempotency & Rate Limits
Guidelines for safe retries across payment, messaging, and OTP APIs.
Payment mutations use idempotency keys to prevent duplicate provider operations when a request is retried after a network failure or timeout.
With @alpha-explora/apicenter-sdk, pass the key as { idempotencyKey }; the client sends the Idempotency-Key header and validates that the value is 16–255 characters. The SDK does not retry mutations automatically. Persist the key with the operation and reuse it with the same request body after a timeout or transient failure. See SDK integration.
Idempotency-Key header
Every payment POST mutation requires an Idempotency-Key header containing 16–255 characters. Reuse the same key with the same request body when retrying the same operation.
Idempotency-Key: 7b9e0f14-3a21-4f92-901b-bf81c94d0e12After a definitive response, APICenter replays the response for the same key and request body for seven days. Reusing a key with a different body returns HTTP 409 with IDEMPOTENCY_KEY_PAYLOAD_MISMATCH. Concurrent reuse returns IDEMPOTENCY_KEY_IN_PROGRESS; retry later with the same key.
If the provider outcome is uncertain, keep using the original key. APICenter allows retries with that key for up to 23 hours from the first attempt, leaving a safety margin before PayMongo's provider idempotency key expires. After that window, APICenter returns HTTP 409 with PAYMENT_OUTCOME_UNKNOWN. Reconcile the payment with APICenter or PayMongo before starting a new operation with a different key.
For payments, referenceId must be unique within (ownerTribeId, consumerServiceId, environment).
Email, SMS, and OTP
Email and SMS sends, OTP generation, and OTP verification also require an Idempotency-Key containing 16–255 characters. Keys are scoped to the authenticated consumer service, tribe, environment, and operation. Reuse the same key with the same request body when retrying.
After a completed operation, APICenter replays the original HTTP status and response body for seven days and includes x-idempotency-replayed: true. A changed body returns HTTP 409 with IDEMPOTENCY_KEY_PAYLOAD_MISMATCH; a concurrent request returns IDEMPOTENCY_KEY_IN_PROGRESS. Rate-limit rejections do not consume the key.
When email/SMS delivery or OTP processing has an uncertain outcome, APICenter keeps the key blocked and returns IDEMPOTENCY_OUTCOME_UNKNOWN on retry. Reconcile the provider message or OTP state before submitting a new request with a different key.
Quotas & rate limits
APICenter applies rate limits per consumer service per minute:
| Category | Limit | Error Code |
|---|---|---|
| Payment Mutations (Create checkout/intent) | 20 req / min | 429 TOO_MANY_REQUESTS |
| Payment Reads (Get status/invoices) | 100 req / min | 429 TOO_MANY_REQUESTS |
| SMS Dispatches | 60 req / min | 429 TOO_MANY_REQUESTS |
| OTP Generation | 10 req / target / min | 429 TOO_MANY_REQUESTS |
Handling rate limits and retries
When receiving HTTP 429, retry after the server's Retry-After value when present, using exponential backoff with jitter. For payment timeouts or 5xx responses, retain the same key and request body. Never create a replacement payment with a new key while the earlier outcome is unresolved.