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

AstroWay використовує кредитну модель замість простого лічильника запитів. Це справедливіше: легкі ендпоінти (/planets) коштують 1 кредит, важкі (/rectification) — 50.

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

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

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

План	Кредитів/міс	Денний ліміт
Free	500	~17
Starter	5 000	~167
Pro	50 000	~1 667
Enterprise	Custom	Custom

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

2. Rate limit (requests per minute)

План	RPM
Free	10 req/min
Starter	60 req/min
Pro	300 req/min
Enterprise	Custom

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

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

Повна таблиця з усіма 87 ендпоінтами — у розділі Тарифи. Короткий орієнтир:

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

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

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

X-Credits-Used: 2
X-Credits-Remaining: 4998
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1714521600
X-Request-Id: 01HXY2A7ZM...

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

Кешування

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

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

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

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

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

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

`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://astroway.info/my-account/subscriptions"
  }
}

Варіанти:

Апгрейд плану — одразу отримуєш новий бюджет
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 × 2 + 1 × 5) × 30 = 500 × 11 × 30 = 165 000 кредитів/міс
→ Pro ($99) покриває

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

Далі

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