Kredyty i limity

AstroWay używa modelu kredytowego zamiast prostego licznika zapytań.

To jest sprawiedliwsze: lekkie endpointy (/planets) kosztują 10 kredytów, ciężkie (/rectification) – 500.

Dwa rodzaje limitów

1. Dzienny/miesięczny budżet kredytów

Liczba kredytów miesięcznie zależy od planu:

Plan	Kredytów/mies	Limit dzienny
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

Gdy tylko kredyty zostaną wyczerpane – kolejne zapytania zwracają 402 Payment Required (Free) lub uruchamiają rozliczanie overage (Indie+).

2. Rate limit (requests per minute)

Plan	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. Jeśli wysłałeś 120 zapytań w 10 sekund, przez kolejne 50 sekund na tym kluczu otrzymasz 429.

Jeśli klucz ma listę dozwolonych pochodzeń, każdy wpis na liście otrzymuje swoją część tego limitu: limit klucza podzielony przez liczbę wpisów, zaokrąglony w górę. Jedna strona z wbudowanym widżetem nie może z tego powodu zużyć całej kwoty, za którą płaci właściciel klucza, a inne jego domeny pozostają funkcjonalne. Ogólny limit klucza nie rośnie: części dzielą go, a nie są do niego dodawane.

Licznik jest prowadzony dla wpisu, a nie dla przychodzącego hosta. Wpis *.example.com to jeden licznik dla wszystkich subdomen, w przeciwnym razie ograniczenie byłoby omijane przez wymyślanie nowej subdomeny dla każdego zapytania. Gdy na liście jest jeden wpis, część jest równa limitowi i nic się nie zmienia.

3. Publiczne endpointy (bez klucza)

14 słowników referencyjnych /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) jest obsługiwanych publicznie, bez X-Api-Key i kosztuje 0 kredytów. Ograniczenie to 30 zapytań / godzinę z jednego IP. Te same dane są udostępnione jako MCP Resources astroway://reference/<slug> dla agentów LLM.

Ten sam limit obowiązuje dla pozostałych publicznych przestrzeni nazw: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Kwota dla renderowania po stronie serwera

30 zapytań na godzinę jest przeznaczonych dla przeglądarki: każdy odwiedzający przynosi własny IP i własną kwotę. Jeśli jednak zapytania wykonuje Twój serwer (wtyczka WordPress, SSR, podgrzewanie cache), jeden adres obsługuje wszystkich odwiedzających i wyczerpuje limit po kilku przeładowaniach strony.

W tym przypadku wyślij nagłówek X-AstroWay-Site-URL z adresem strony:

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

Tryb	Limit
Bez nagłówka	30 zapytań / godzinę na IP; widżety `/v1/embed/*` mają osobne 120 / godzinę na IP
Z nagłówkiem	300 zapytań / godzinę na stronę, limit 600 / godzinę na IP

Nagłówek jest dozwolony w CORS i nie stanowi danych uwierzytelniających, dlatego limit na IP pozostaje: niezależnie od tego, ile domen zostanie zgłoszonych z jednego adresu, łącznie z tego adresu nie zostanie wysłanych więcej niż 600 zapytań na godzinę. Oba liczniki są potrzebne jednocześnie: licznik strony uruchamia się, gdy jedna strona korzysta z wielu adresów (CDN, load balancer), licznik IP uruchamia się, gdy z jednego adresu przychodzi wiele nazw.

Jedno wywołanie nie zawsze jest jedną jednostką. Ciężki publiczny endpoint zużywa więcej z tego samego koszyka, a nie otrzymuje osobnego. POST /v1/public/synastry kosztuje 3, ponieważ to dwie mapy i macierz aspektów na 45 komórek: praktyczny limit dla niego to 10 na godzinę z niezgłoszonego adresu, 100 na zgłoszoną stronę i 200 na adres. Wszystko inne kosztuje 1. Gdy wywołanie kosztuje więcej niż jedną jednostkę, odpowiedź informuje o tym w nagłówku X-RateLimit-Cost, a wywołanie, które kosztuje więcej niż pozostało w koszyku, jest odrzucane, a nie idzie na minus.

Który licznik jest obecnie najbardziej restrykcyjny, informuje nagłówek odpowiedzi X-RateLimit-Scope (ip lub site). Pozostałe nagłówki X-RateLimit-* opisują właśnie jego, czyli tylko jeden licznik z dwóch. Drugi jest widoczny w X-RateLimit-Counters:

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

Format to scope=pozostało/limit oddzielone przecinkiem. Nagłówek pojawia się tylko wtedy, gdy liczniki są rzeczywiście dwa: anonimowe wywołanie z X-AstroWay-Site-URL. Wywołanie z płatnym kluczem jest liczone według Twojego klucza i Twojej taryfy, tam licznik jest jeden i nagłówka nie ma. Czytaj go, jeśli renderujesz z serwera kilka domen z jednego adresu: koszyk strony dla każdej domeny jest własny, a limit na IP jest wspólny, i to właśnie on jest osiągany jako pierwszy.

Cache’uj odpowiedzi po swojej stronie: dzienny horoskop nie zmienia się w ciągu doby, a cache do północy całkowicie rozwiązuje kwestię limitu.

Płatny klucz na publicznych endpointach. /v1/public/* oraz /v1/embed/* działają bez klucza, ale jeśli go przekażesz (X-Api-Key), zapytanie jest liczone według Twojej taryfy, a nie anonimowej kwoty, i w odpowiedzi nie ma darmowego znaku wodnego. Ma to sens dla renderowania po stronie serwera: jedna maszyna obsługuje wszystkich odwiedzających, a anonimowe 300/godz. to dla niej za mało.

Tabela kosztów

Pełna, przejrzysta tabela ze wszystkimi 771+ endpointami i ich kosztami – na stronie Koszty endpointów. DivineAPI/AstrologyAPI/Prokerala takiej tabeli nie publikują. Krótki przewodnik:

Tier	Kredytów	Typowy czas	Przykłady
1	10	< 50 ms	`/planets`, `/moon-voc`, `/iching`
2	20	50–200 ms	`/chart`, `/harmonics`, `/horary`
3	50	200–500 ms	`/synastry`, `/progressions`, `/acg`
4	100	> 500 ms	`/transit-calendar`, `/forecast-calendar`
5	250	kilka s	`/rectification/trutine`
6	500	do 120 s	`/rectification`

Nagłówki odpowiedzi

Każda odpowiedź zawiera:

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-RateLimit-Origin-Limit: 60
X-RateLimit-Origin-Remaining: 59
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

X-Credits-Used: ile zostało odpisane za to zapytanie
X-Credits-Remaining: pozostałość w miesięcznym budżecie
X-Credits-Limit: pełny budżet kredytów na miesiąc (zgodnie z planem)
X-Credits-Reset: data odnowienia salda w formacie ISO-8601
X-RateLimit-*: bieżący stan sliding window (standardowy format)
- X-RateLimit-Scope: który licznik jest obecnie najbardziej restrykcyjny: ip, site lub key. Wartość key oznacza, że zapytanie zostało policzone według Twojego klucza i limitu Twojej taryfy, a nie anonimowej kwoty.
- X-RateLimit-Counters: na publicznym endpoincie, wywołanym z X-AstroWay-Site-URL, wszystkie liczniki, według których zapytanie było liczone, w formacie scope=pozostało/limit. Nagłówki powyżej opisują tylko najbardziej restrykcyjny.
- X-RateLimit-Reset: moment, w którym z okna wypadnie najstarsze zapytanie, czyli kiedy zwolni się jeden slot. To nie jest czas pełnego otwarcia bucketa: po nim przejdzie jedno zapytanie, a Reset przesunie się na następne w kolejności. Klient, który czeka do Reset, a potem wysyła paczkę, ponownie otrzyma 429, dlatego bezpieczniej jest wysyłać po jednym zapytaniu lub cache’ować odpowiedzi po swojej stronie.
- Odrzucone zapytanie (429) nie zużywa kwoty i nie przesuwa okna: licznik jest uzupełniany tylko udanymi zapytaniami.
- X-RateLimit-Origin-Limit i X-RateLimit-Origin-Remaining: pojawiają się tylko wtedy, gdy zapytanie przeszło dla wpisu z listy dozwolonych pochodzeń i pokazują część, która została przydzielona właśnie temu wpisowi. Odmowa z powodu tej części również jest 429, a w tekście jest podane, który wpis został wyczerpany.
X-Subscription-Status i X-Subscription-Grace-Ends: pojawiają się tylko wtedy, gdy opłacony okres już się zakończył, a 3-dniowy okres karencji nadal trwa (X-Subscription-Status: grace). Zapytania są obsługiwane według Twojej taryfy do momentu wskazanego w X-Subscription-Grace-Ends, po nim odpowiedź to 402 SUBSCRIPTION_EXPIRED. Jeśli Twój klient loguje nagłówki, to jest to najwcześniejszy sygnał, że czas przedłużyć plan.
X-Request-Id: identyfikator zapytania, 32 znaki szesnastkowe; podaj go, kontaktując się z pomocą techniczną

Ile już wydano: trzy sposoby

Możesz sprawdzić bieżące saldo kredytów na trzy sposoby – od najszybszego do najbardziej szczegółowego:

W każdej odpowiedzi: nagłówki X-Credits-Remaining / X-Credits-Used / X-Credits-Limit są zwracane dla każdego zapytania (nawet w przypadku błędu). Nie musisz wywoływać niczego dodatkowego – saldo jest zawsze widoczne.
Osobnym zapytaniem: GET /v1/keys/usage z Twoim X-Api-Key zwraca credits (used / remaining / limit / reset), usage (zapytań za today / week / month) i top-20 endpointów z ostatnich 30 dni. Jedno wywołanie, bez osobnego klucza admina.
W panelu sterowania: api.astroway.info/dashboard/billing pokazuje saldo, wykres usage i podział według endpointów w czasie rzeczywistym.

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

Cache’owanie

Identyczne zapytania w ciągu 5 minut są zwracane z cache’u bez pobierania kredytów. To osobny nagłówek:

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

Co jest uważane za “identyczne”:

Ten sam endpoint
To samo JSON body (bajt po bajcie po normalizacji spacji)
Ten sam klucz API

Jest to bezpieczne, ponieważ wszystkie endpointy są deterministyczne – ten sam input zawsze daje ten sam output.

Streaming i webhooki

Streaming (`/stream/*`)

10 endpointów strumieniowych jest taryfikowanych jako Tier 1: 10 kredytów za wywołanie. Każde wywołanie przelicza pozycje planet, więc jest to pełnoprawne obliczenie, a nie cache’owane wyszukiwanie – nie ma osobnej “tańszej” stawki za tick.

Każda odpowiedź zawiera dwa pola do ekonomicznego odpytywania:

tickSeconds: zalecany interwał odpytywania;
nextEventAt: kiedy stan zmieni się następnym razem.

Odpytywanie częściej niż tickSeconds to marnowanie kredytów: stan nie zmieni się do nextEventAt.

Webhooki (`/webhooks/*`)

Operacje CRUD zarządzania subskrypcją (/webhooks/subscribe, lista, podgląd, usunięcie, /test) kosztują Tier 1: 10 kredytów każda. To rzadkie wywołania.

Dostarczanie zdarzeń (serwer → Twój URL) nie jest taryfikowane: kredyty są pobierane tylko za wywołania CRUD zarządzania. Obsługiwanych jest 12 typów zdarzeń (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress itd.).

Webhooki są dostępne od planu Pro i wyżej.

Co robić w przypadku przekroczenia limitów

`402 Payment Required`: skończyły się kredyty

{
  "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"
  }
}

Opcje:

Upgrade planu: od razu otrzymujesz nowy budżet
Overage (Starter/Pro): włącza się automatycznie, jeśli nie jest wyłączony w settings
Czekać na reset (Free): 1. dzień następnego miesiąca

`429 Too Many Requests`: przekroczono RPM

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

Nagłówek Retry-After: 12 – standardowy nagłówek HTTP, Twój klient HTTP powinien go rozumieć.

Prawidłowa obsługa:

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();
}

Wycena budżetu z wyprzedzeniem

Przed integracją oszacuj, ile kredytów potrzebujesz miesięcznie:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Przykład: aplikacja z 500 DAU, każdy użytkownik wykonuje 3 obliczenia map + 1 synastrię dziennie:

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1,650,000 credits/mo
→ Enterprise (custom)

Kalkulator budżetu – na stronie Taryfy.

Dalej

Błędy: pełny przewodnik po kodach błędów
Idempotency: jak bezpiecznie wykonywać powtórne zapytania

Przydatne?

Zaproponuj edycję

Ostatnia aktualizacja: 5 paź 2026