> ## Documentation Index
> Fetch the complete documentation index at: https://developers.callaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency and Retries

> Apply idempotent retry design across billing and side-effecting flows without creating duplicate financial or operational actions.

# 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

<Steps>
  <Step title="Generate one key per business intent">
    Use deterministic keys (for example `alloc:{partner_ref}:{invoice_id}`) when replay risk is high.
  </Step>

  <Step title="Persist key and request metadata before sending">
    Store payload hash, created\_at, and owning job ID.
  </Step>

  <Step title="Retry only on transient failures">
    Retry network timeouts, 429, and selected 5xx responses with backoff.
  </Step>

  <Step title="Treat response mismatch as incident">
    If same idempotency key returns conflicting results, quarantine and escalate.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  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}'
  ```

  ```javascript Node.js theme={null}
  const idempotencyKey = 'alloc-partnerA-tenant123-inv8891';

  await fetch('https://api.callaro.ai/api/v1/billing/allocate-credits', {
    method: 'POST',
    headers: {
      'X-Partner-Api-Key': process.env.CALLARO_PARTNER_KEY,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ tenant_id: 123, amount_major: 5000 })
  });
  ```
</CodeGroup>

## 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)

<Note>
  If an endpoint does not explicitly support `Idempotency-Key`, make your consumer idempotent with external IDs and dedupe storage in your own system.
</Note>