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

Nội dung này hiện chưa có sẵn bằng ngôn ngữ của bạn.

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-агентів.

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

Повна прозора таблиця з усіма 723+ ендпоінтами і їх вартістю — на сторінці Вартість ендпоінтів. 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: 01HXY2A7ZM...

X-Credits-Used — скільки списано за цей запит
X-Credits-Remaining — залишок на місячному бюджеті
X-Credits-Limit — повний бюджет кредитів на місяць (за планом)
X-Credits-Reset — ISO-8601 дата оновлення балансу
X-RateLimit-* — поточний стан sliding window (стандартний формат)
X-Request-Id — ULID запиту, використай при зверненні в підтримку

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

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

У кожній відповіді — заголовки 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 — як робити повторні запити безпечно

Hữu ích chứ?

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

Cập nhật lần cuối: 17 thg 6, 2026