Skip to main content

​
Idempotency must be scoped to business action boundaries.

Use Idempotency-Key where supported to make retries safe for side-effecting operations.

​
Where idempotency is highest priority

  • Partner billing credit allocation/deallocation flows
  • Financially sensitive write operations
  • External action fan-outs where duplicate writes are costly

​
Safe retry pattern

1

Generate one key per business intent

Use deterministic keys (for example alloc:{partner_ref}:{invoice_id}) when replay risk is high.
2

Persist key and request metadata before sending

Store payload hash, created_at, and owning job ID.
3

Retry only on transient failures

Retry network timeouts, 429, and selected 5xx responses with backoff.
4

Treat response mismatch as incident

If same idempotency key returns conflicting results, quarantine and escalate.
curl -X POST "https://api.callaro.ai/api/v1/billing/allocate-credits" \
  -H "X-Partner-Api-Key: $CALLARO_PARTNER_KEY" \
  -H "Idempotency-Key: alloc-partnerA-tenant123-inv8891" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":123,"amount_major":5000}'

​
What not to do

  • Do not generate a new key for each retry attempt.
  • Do not reuse one key across unrelated business actions.
  • Do not retry validation or authorization failures with same payload indefinitely.

​
Reconciliation fields to log

  • idempotency_key
  • endpoint path
  • payload hash
  • response request_id
  • response status and error code (if any)
If an endpoint does not explicitly support Idempotency-Key, make your consumer idempotent with external IDs and dedupe storage in your own system.