Кредити та ліміти

Tento obsah zatím není dostupný ve vašem jazyce.

AstroWay використовує кредитну модель замість простого лічильника запитів.

Це справедливіше: легкі ендпоінти (/planets) коштують 10 кредитів, важкі (/rectification) - 500.

Два види лімітів

1. Денний/місячний бюджет кредитів

Кількість кредитів на місяць залежить від плану:

План	Кредитів/міс	Денний ліміт
Free	10 000	~333
Indie	50 000	~1 667
Starter	200 000	~6 667
Pro	800 000	~26 667
Business	3 500 000	~116 666
Enterprise	Custom	Custom

Щойно кредити вичерпано - наступні запити повертають 402 Payment Required (Free) або запускають overage-білінг (Indie+).

2. Rate limit (requests per minute)

План	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	Custom

Rate limit - sliding window. Якщо вистрілив 120 запитів за 10 секунд, наступні 50 секунд на цьому ключі - 429.

3. Публічні ендпоінти (без ключа)

14 reference-словників /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) обслуговуються публічно, без X-Api-Key і коштують 0 кредитів. Обмеження - 30 запитів / годину з одного IP. Ці ж дані виставлені як MCP Resources astroway://reference/<slug> для LLM-агентів.

Той самий ліміт діє на решту публічних namespace: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Квота для рендеру на сервері

30 запитів на годину розраховані на браузер: кожен відвідувач приносить власний IP і власну квоту. Якщо ж запити робить ваш сервер (WordPress-плагін, SSR, кеш-прогрів), одна адреса ходить за всіх відвідувачів і вичерпує ліміт за кілька перезавантажень сторінки.

Для цього випадку надішліть заголовок X-AstroWay-Site-URL з адресою сайту:

X-AstroWay-Site-URL: https://example.com/

Режим	Ліміт
Без заголовка	30 запитів / годину на IP
Із заголовком	300 запитів / годину на сайт, стеля 600 / годину на IP

Заголовок дозволений у CORS і не є обліковими даними, тому стеля на IP залишається: скільки б доменів не назвали з однієї адреси, сумарно звідти піде не більше за 600 запитів на годину. Обидва лічильники потрібні одночасно: лічильник сайту спрацьовує, коли один сайт ходить з багатьох адрес (CDN, балансувальник), лічильник IP спрацьовує, коли з однієї адреси приходить багато імен.

Один виклик не завжди одна одиниця. Важкий публічний ендпоінт витрачає більше тієї самої корзини, а не отримує окрему. POST /v1/public/synastry коштує 3, бо це дві карти й матриця аспектів на 45 клітинок: практична стеля для нього це 10 на годину з незаявленої адреси, 100 на заявлений сайт і 200 на адресу. Все інше коштує 1. Коли виклик коштує більше за одиницю, відповідь каже це в заголовку X-RateLimit-Cost, а виклик, який коштує більше, ніж лишилося в корзині, відхиляється, а не йде в мінус.

Який лічильник зараз найтісніший, каже заголовок відповіді X-RateLimit-Scope (ip або site). Решта заголовків X-RateLimit-* описують саме його, тобто тільки один лічильник з двох. Другий видно в X-RateLimit-Counters:

X-RateLimit-Scope: site
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Counters: ip=597/600, site=297/300

Формат - scope=залишок/ліміт через кому. Заголовок приходить тільки тоді, коли лічильників справді два: анонімний виклик із X-AstroWay-Site-URL. Виклик із платним ключем рахується за ключем і за вашим тарифом, там лічильник один і заголовка немає. Читайте його, якщо рендерите з сервера кілька доменів з однієї адреси: корзина сайту в кожного домену своя, а стеля на IP спільна, і саме вона впирається першою.

Кешуйте відповіді на своєму боці: денний гороскоп не змінюється протягом доби, і кеш до півночі знімає питання ліміту повністю.

Платний ключ на публічних ендпоінтах. /v1/public/* та /v1/embed/* працюють без ключа, але якщо ви його передасте (X-Api-Key), запит рахується за вашим тарифом, а не за анонімною квотою, і у відповіді немає безкоштовного водяного знака. Це має сенс для server-side рендера: одна машина ходить за всіх відвідувачів, і анонімних 300/год їй мало.

Таблиця вартості

Повна прозора таблиця з усіма 748+ ендпоінтами і їх вартістю - на сторінці Вартість ендпоінтів. DivineAPI/AstrologyAPI/Prokerala такої таблиці не публікують. Короткий орієнтир:

Tier	Кредитів	Типовий час	Приклади
1	10	< 50 мс	`/planets`, `/moon-voc`, `/iching`
2	20	50–200 мс	`/chart`, `/harmonics`, `/horary`
3	50	200–500 мс	`/synastry`, `/progressions`, `/acg`
4	100	> 500 мс	`/transit-calendar`, `/forecast-calendar`
5	250	кілька с	`/rectification/trutine`
6	500	до 120 с	`/rectification`

Заголовки відповіді

Кожна відповідь містить:

X-Credits-Used: 20
X-Credits-Remaining: 9980
X-Credits-Limit: 10000
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714521600
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

X-Credits-Used: скільки списано за цей запит
X-Credits-Remaining: залишок на місячному бюджеті
X-Credits-Limit: повний бюджет кредитів на місяць (за планом)
X-Credits-Reset: ISO-8601 дата оновлення балансу
X-RateLimit-*: поточний стан sliding window (стандартний формат)
- X-RateLimit-Scope: який лічильник зараз найтісніший: ip, site або key. Значення key означає, що запит порахований за вашим ключем і за лімітом вашого тарифу, а не за анонімною квотою.
- X-RateLimit-Counters: на публічному ендпоінті, викликаному з X-AstroWay-Site-URL, усі лічильники, за якими рахувався запит, у форматі scope=залишок/ліміт. Заголовки вище описують лише найтісніший.
- X-RateLimit-Reset: момент, коли з вікна випаде найстаріший запит, тобто коли звільниться один слот. Це не час повного відкриття бакета: після нього пройде один запит, і Reset зсунеться на наступний за часом. Клієнт, який чекає до Reset і потім шле пачку, знову отримає 429, тому надійніше йти по одному запиту або кешувати відповіді на своєму боці.
- Відхилений запит (429) квоти не витрачає і вікно не зсуває: лічильник поповнюється тільки успішними запитами.
X-Request-Id: ідентифікатор запиту, 32 шістнадцяткові символи; назви його при зверненні в підтримку

Скільки вже витрачено: три способи

Перевірити поточний баланс кредитів можна трьома способами - від найшвидшого до найдетальнішого:

У кожній відповіді: заголовки X-Credits-Remaining / X-Credits-Used / X-Credits-Limit повертаються на будь-який запит (навіть на помилку). Нічого додатково викликати не треба - баланс завжди перед очима.
Окремим запитом: GET /v1/keys/usage зі своїм X-Api-Key повертає credits (used / remaining / limit / reset), usage (запитів за today / week / month) і топ-20 ендпоінтів за 30 днів. Один виклик, без окремого admin-ключа.
У дашборді: api.astroway.info/dashboard/billing показує баланс, графік usage і розбивку по ендпоінтах у реальному часі.

curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"

Кешування

Ідентичні запити протягом 5 хвилин повертаються з кешу без списання кредитів. Це окремий заголовок:

X-Cache: HIT
X-Credits-Used: 0

Що вважається «ідентичним»:

Той самий ендпоінт
Той самий JSON body (байт-в-байт після нормалізації пробілів)
Той самий ключ API

Це безпечно, бо всі ендпоінти детерміновані - однаковий input завжди дає однаковий output.

Стрімінг і вебхуки

Стрімінг (`/stream/*`)

10 стрім-ендпоінтів тарифікуються як Tier 1: 10 кредитів за виклик. Кожен виклик перераховує позиції планет, тому це повноцінне обчислення, а не кешований lookup - окремої «дешевшої» ставки за тік немає.

Кожна відповідь містить два поля для економного опитування:

tickSeconds: рекомендований інтервал опитування;
nextEventAt: коли стан зміниться наступного разу.

Опитувати частіше за tickSeconds - марно палити кредити: стан не зміниться до nextEventAt.

Вебхуки (`/webhooks/*`)

CRUD-операції керування підпискою (/webhooks/subscribe, список, перегляд, видалення, /test) коштують Tier 1: 10 кредитів кожна. Це рідкісні виклики.

Доставка події (сервер → ваш URL) не тарифікується: кредити списуються лише за CRUD-виклики керування. Підтримується 12 типів подій (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress тощо).

Вебхуки доступні з плану Pro і вище.

Що робити при перевищенні лімітів

`402 Payment Required`: закінчились кредити

{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit budget exhausted. Upgrade plan or wait for reset.",
    "credits_remaining": 0,
    "credits_reset": "2026-05-01T00:00:00Z",
    "upgrade_url": "https://api.astroway.info/dashboard/billing"
  }
}

Варіанти:

Апгрейд плану: одразу отримуєш новий бюджет
Overage (Starter/Pro): вмикається автоматично, якщо не вимкнено в settings
Чекати reset (Free): 1 число наступного місяця

`429 Too Many Requests`: перевищено RPM

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after_seconds": 12
  }
}

Заголовок Retry-After: 12 - стандартний HTTP-заголовок, твій HTTP-клієнт має його розуміти.

Правильна обробка:

async function callWithRetry(endpoint: string, body: object) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callWithRetry(endpoint, body);
  }

  return response.json();
}

Оцінка бюджету заздалегідь

Перед інтеграцією прикинь, скільки кредитів тобі потрібно на місяць:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Приклад: застосунок на 500 DAU, кожен користувач робить 3 розрахунки карт + 1 синастрію на день:

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1 650 000 кредитів/міс
→ Business ($199) покриває

Калькулятор бюджету - на сторінці Тарифи.

Далі

Помилки: повний довідник error-кодів
Idempotency: як робити повторні запити безпечно

Užitečné?

Запропонувати правку

Aktualizováno: 22. 8. 2026