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

# Making fetchbean requests idempotent and retry-safe

> Send an Idempotency-Key header to make any fetchbean call exactly-once safe — retries return the cached result without triggering a second credit charge.

Network calls fail and get retried — that's a fact of distributed systems. Without a way to deduplicate retries, a transient timeout can cause the same operation to run twice, costing credits twice and potentially returning duplicate results. fetchbean solves this with the `Idempotency-Key` header, which makes any call exactly-once safe regardless of how many times you send it.

## Sending an idempotency key

Add the `Idempotency-Key` header to any request. Use a unique value per logical operation — a UUID is the best choice:

```bash theme={null}
curl https://api.fetchbean.com/v1/search \
  -H "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f8c1e2a-4b3c-..." \
  -d '{"query":"best vector databases"}'
```

<Tip>
  Generate a fresh UUID for each distinct operation. Reuse the same UUID only when retrying the same logical request — for example, after a network timeout on the original attempt.
</Tip>

## Retry behaviour

The outcome when you resend a request with the same key depends on the state of the original call:

<CardGroup cols={2}>
  <Card title="Original succeeded" icon="circle-check">
    fetchbean returns the original result immediately. **You are not charged again** — no second reserve, no second settle.
  </Card>

  <Card title="Original in flight" icon="clock">
    fetchbean returns a `request_in_progress` response instead of dispatching a second call. Wait and retry.
  </Card>

  <Card title="Original failed" icon="circle-xmark">
    The key is spent. Use a **new key** for your next attempt — the failed call is not replayed.
  </Card>

  <Card title="No key sent" icon="key">
    fetchbean generates a unique key for you automatically. Every call without a key is treated as a distinct operation.
  </Card>
</CardGroup>

## Billing protection

Idempotency and billing are tightly coupled in fetchbean. A call that reserves credits upfront only ever settles once — a same-key retry never triggers a second reservation or a second charge. This means you can safely retry on timeouts, connection drops, or any network error without worrying about being billed multiple times for a single logical operation.

<Note>
  If you omit the `Idempotency-Key` header entirely, fetchbean assigns a generated key automatically. This means every headerless call is treated as a unique request — no deduplication occurs.
</Note>