# Idempotency

Усі ендпоінти AstroWay API **природно ідемпотентні**: однаковий input завжди дає однаковий output, ніяких бічних ефектів (крім списання кредитів і логування usage).

Це означає, що retry при мережевих помилках — безпечний. Але щоб повторний запит **не списував кредити двічі**, треба передати `Idempotency-Key` header.

## Як використовувати

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

{ "datetime": "1990-07-14T14:30:00", ... }
```

`Idempotency-Key` — довільний рядок до 64 символів, унікальний для кожної логічної операції. Рекомендовано — ULID або UUID v4.

## Гарантії

- Протягом **24 годин** після першого запиту з цим ключем, повторні запити з тим самим ключем повертають **той самий response** без повторного розрахунку і **без списання кредитів**.
- Якщо body запиту відрізняється від оригіналу — повертається `409 Conflict` з кодом `idempotency_key_reuse`.
- Через 24 години ключ забувається, новий запит з таким же ключем буде звичайним.

<br />

:::note
Idempotency — це захист від **подвійного списання** при мережевих збоях, а не кеш. Для кешування використовуй природний `X-Cache` механізм (5 хвилин, дивись [Кредити та ліміти](/rate-limits-credits/)).
:::

## Коли це потрібно

- У webhook-handler-ах, де retry приходить від зовнішньої системи (наприклад, payment-провайдер або CRM шле подію, яку ти парсиш і робиш розрахунок)
- У фонових job-ах, де retry — стандартна поведінка при збоях
- У CI/CD pipeline, де тест може запуститись повторно

Для звичайних взаємодій «користувач натиснув кнопку → показали карту» ідемпотентність не потрібна — користувач і так побачить результат, повторних кліків зазвичай немає.

## Коли **не** використовувати

- Не став ключ, щоб зекономити кредити на однакових запитах — для цього є `X-Cache` (безкоштовний, 5 хвилин)
- Не генеруй ключ з hash(body) — тоді ти втратиш дефолтну поведінку Idempotency-Key (повторний `409` при розбіжності body)