Idempotency

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

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

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

POST /v1/chart HTTP/1.1
X-Api-Key: sk_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 години ключ забувається, новий запит з таким же ключем буде звичайним.

Заувага

Idempotency — це захист від подвійного списання при мережевих збоях, а не кеш. Для кешування використовуй природний X-Cache механізм (5 хвилин, дивись Кредити та ліміти).

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

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

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

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

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