Автентифікація
Один заголовок, один ключ і кілька помилок — кожна означає щось цілком конкретне.
Заголовок
Передавайте ключ у заголовку X-API-Key у кожному запиті. Жодного OAuth, обміну токенами чи їх оновлення.
curl -X POST https://api.occultapi.com/api/astro/tithi/ \
-H "X-API-Key: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF" \
-H "Content-Type: application/json" \
-d '{ "date_time": "2026-09-16T06:00:00+05:30", "latitude": 26.9124, "longitude": 75.7873, "timezone_as_float": 5.5 }'Формат ключа
Ключ має такий вигляд: yt_live_a1b2c3d4_x9K2mQ7vB4nR8sL1wY6tZ3pC5hJ0dF — бренд, середовище, публічний префікс із восьми символів і секрет.
yt_live_…витрачає справжні кредити з вашого балансу.yt_test_…— для розробки; у записах про використання він так і позначений.
Префікс навмисно публічний і проіндексований. Якщо ключ колись потрапить у публічний репозиторій, його можна знайти й відкликати за самим префіксом — секретна частина для цього не потрібна.
Показується раз, зберігається як хеш
Ключ показується рівно один раз — коли ви його створюєте. Ми зберігаємо лише хеш SHA-256, тож відновити ключ не зможе ні адміністратор, ні той, хто отримає дамп бази даних. Це також означає, що надіслати ключ повторно ми справді не можемо. Далі ви бачите тільки префікс і останні чотири символи — цього досить, щоб відрізнити ключі в списку.
Загубили ключ? Створіть новий і відкличте старий. Це швидше, ніж писати нам, і нічого іншого ми все одно не змогли б зробити.
Помилки — і які з них не про автентифікацію
Кожна помилка приходить у стандартному форматі з is_error: true і незмінним машинним кодом у message. Будуйте логіку на коді, а не на тексті.
| Статус | message | Що це означає | Що робити |
|---|---|---|---|
| 401 | invalid_api_key | Ключа немає, він має хибний формат, відкликаний або термін його дії минув. | Перевірте, чи заголовок X-API-Key справді до нас доходить. Якщо ви замінили ключ, розгорніть новий. |
| 402 | insufficient_credits | Ключ дійсний, але баланс порожній. | Перейдіть на більший тариф або дочекайтеся щомісячного оновлення квоти. Автентифікація тут ні до чого — новий ключ не допоможе. |
| 403 | endpoint_not_allowed | Цей маршрут недоступний для API-ключів: хибний шлях чи метод або ендпоінт більше не працює. | Звірте маршрут і метод із довідником. Не допоможе ні повторна спроба, ні новий ключ. |
| 403 | scope_not_allowed | У ключа немає дозволу (scope), потрібного цьому ендпоінту. | Створіть ключ із потрібними дозволами або залиште список дозволів порожнім, щоб дозволити все. |
| 403 | ip_not_allowed | Для ключа задано список дозволених IP, а запит прийшов з адреси, якої в ньому немає. | Викликайте API з дозволеної IP-адреси або створіть ключ із правильними IP — чи взагалі без них, щоб дозволити будь-яку. |
| 403 | account_suspended | Акаунт призупинено, тому всі його ключі відхиляються. | Напишіть у підтримку. Новий ключ не допоможе. |
| 429 | api_key_rate_limited | Забагато запитів за хвилину з цим ключем. | Зачекайте стільки секунд, скільки вказано в заголовку Retry-After, і повторіть запит. |
| 400 | (помилки в полях) | У тілі запиту помилка. У message названо кожне хибне поле. | Прочитайте message — там усе конкретно. Кредити за це не списуються. |
Повторимо ще раз: 402 — це не помилка автентифікації. Ключ справний, просто баланс порожній. Створювати новий ключ — типова помилка, яка нічого не змінює.
Заголовки з кредитами
Кожна відповідь повідомляє, скільки коштував виклик і скільки лишилося, тож витрати видно без окремого запиту.
X-Credits-Cost: 1 # what this endpoint costs
X-Credits-Charged: 1 # what you were actually billed — 0 on any error
X-Credits-Remaining: 149 # balance after this callЗаписуйте в лог саме X-Credits-Charged. Для невдалого запиту там завжди 0: кредит резервується перед розрахунком і повертається, якщо той не завершився успішно. Тож поки ви налагоджуєте інтеграцію, помилки в ній не з’їдять баланс.
Ліміти запитів
Ліміти діють на кожен ключ окремо й рахуються за хвилину. Вони потрібні, щоб стримати ключ, який потрапив у чужі руки, а не щоб обмежувати вас. Якщо перевищите ліміт, отримаєте 429 із заголовком Retry-After — це кількість секунд, яку треба зачекати, перш ніж повторювати запит. Відповіді також містять X-RateLimit-Limit і X-RateLimit-Remaining.
За 429 кредити не списуються ніколи. Якщо ви впираєтеся в ліміт за звичайної роботи, напишіть нам — ми його підвищимо.
Як уберегти ключ
- Викликайте API зі свого сервера, а не з браузера. Ключ у фронтенд-бандлі чи мобільному застосунку — публічний, хоч як його назвіть. Будь-хто може його прочитати й витратити ваш баланс.
- Тримайте ключ у змінній середовища або в менеджері секретів. Ніколи не комітьте його.
- Для кожного середовища використовуйте окремий ключ — тоді один можна відкликати, не зупиняючи інші.
- Ротація: створіть новий ключ, розгорніть його, а тоді відкличте старий. Саме в такому порядку — щоб ніщо не впало в проміжку.
- Якщо ключ міг потрапити в чужі руки, негайно відкличте його. Відкликання діє одразу, а ваші кредити лишаються на балансі.
Усе це — на сторінці ключів.