Reliability & Fault-Tolerance

Request Idempotency

The Superchat API supports idempotency keys to safely retry requests without accidentally performing the same operation twice.

Why Idempotency Matters

When an API call fails due to a network timeout or connection reset, you cannot know whether the server executed the request before the connection was dropped. Sending an `Idempotency-Key` header guarantees that if a request is received again, the API returns the original cached response without creating a duplicate payment session.

Sending the Idempotency Header

# Send a unique UUID or internal order ID

curl -X POST https://api.superchatbd.com/api/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: e86b4f7e-9cf4-4b53-936c-dfc5bc79ef2a" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 500,
        "success_url": "https://myshop.com/orders/12345/success",
        "cancel_url": "https://myshop.com/cart"
      }'

The header applies to POST requests. A replayed response carries Idempotent-Replayed: true and the original status code, so you can tell a replay from a fresh payment.

Idempotency Behavior

Keys are cached for 24 hours, scoped to your developer account.
A retry with the same key receives the identical response body and status code, and never creates a second payment session.
The cache is written when a request finishes, so two simultaneous calls with one key are not serialised — build the key per logical operation and reuse it only for retries of that operation.
The official SDKs send an idempotency key automatically on payments.create() and reuse it across their own retries.