# Idempotency

All AstroWay API endpoints are **naturally idempotent**: same input always produces same output, no side effects (except credit consumption and usage logging).

This means retrying on network errors is safe. But to ensure a retry **doesn't charge credits twice**, pass an `Idempotency-Key` header.

## How to use

```http
POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "date": "1990-07-14", "time": "14:30:00", ... }
```

`Idempotency-Key` — arbitrary string up to 64 characters, unique per logical operation. Recommended: ULID or UUID v4.

## Guarantees

- For **24 hours** after the first request with a given key, repeat requests with the same key return **the same response** without recalculation and **without charging credits**.
- If the request body differs from the original — returns `409 Conflict` with code `idempotency_key_reuse`.
- After 24 hours the key is forgotten; a new request with the same key is treated as a normal new request.

<br />

:::note
Idempotency protects against **double-charging** on network failures, not caching. For caching, use the built-in `X-Cache` mechanism (5 minutes — see [Credits & Rate Limits](/en/rate-limits-credits/)).
:::

## When you need it

- In webhook handlers where retries come from an external system (e.g. a payment provider or CRM sending events you parse and use for a calculation)
- In background jobs where retry is standard behavior on failures
- In CI/CD pipelines where a test may run multiple times

For normal "user clicks a button → show a chart" flows, idempotency isn't needed — the user sees the result anyway, repeat clicks are rare.

## When **not** to use

- Don't set the key to save credits on identical requests — use `X-Cache` for that (free, 5 minutes)
- Don't generate the key from `hash(body)` — you'd lose the default Idempotency-Key behavior (repeat `409` on body mismatch)