Kreditek és korlátok

Az AstroWay kreditmodellt használ az egyszerű lekérdezésszámláló helyett.

Ez igazságosabb: az egyszerű végpontok (/planets) 10 kreditbe, a bonyolultabbak (/rectification) 500 kreditbe kerülnek.

Kétféle limit

1. Napi/havi kreditkeret

A havi kreditek száma a csomagtól függ:

Csomag	Kreditek/hó	Napi limit
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

Amint a kreditek elfogytak, a következő kérések 402 Payment Required (Free) hibát adnak vissza, vagy elindul az overage-számlázás (Indie+).

2. Kérések száma percenként (Rate limit)

Csomag	Kérések/perc
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	Custom

A rate limit egy csúszó ablakos rendszer. Ha 120 kérést küldtél 10 másodperc alatt, akkor a következő 50 másodpercben ezen a kulcson 429 hibát kapsz.

Ha egy kulcshoz engedélyezett források listája tartozik, a lista minden bejegyzése megkapja a limit saját részét: a kulcs limitje elosztva a bejegyzések számával, felfelé kerekítve. Egy beágyazott widgettel rendelkező webhely emiatt nem fogyaszthatja el a kulcstulajdonos által fizetett kvótát, miközben a többi domainje működőképes marad. A kulcs teljes limitje nem nő: a részek megosztják azt, nem pedig hozzáadódnak hozzá.

A számláló a bejegyzés alapján működik, nem a beérkező hoszt alapján. A *.example.com bejegyzés egyetlen számlálót jelent az összes aldomainre, különben a korlátozást minden kéréshez új aldomain kitalálásával lehetne megkerülni. Ha a listában csak egy bejegyzés van, a rész megegyezik a limittel, és semmi sem változik.

3. Nyilvános végpontok (kulcs nélkül)

14 referencia-szótár /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) nyilvánosan, X-Api-Key nélkül érhető el, és 0 kreditbe kerül. A korlátozás – 30 kérés / óra egy IP-ről. Ugyanezek az adatok MCP erőforrásként astroway://reference/<slug> formában is elérhetők LLM-ügynökök számára.

Ugyanez a limit vonatkozik a többi nyilvános névtérre: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Kvóta szerveroldali rendereléshez

A 30 kérés/óra a böngészőre van méretezve: minden látogató saját IP-címmel és saját kvótával rendelkezik. Ha azonban a kéréseket a szervered (WordPress-plugin, SSR, gyorsítótár-melegítés) küldi, egyetlen címről történik az összes látogató nevében, és néhány oldalfrissítés alatt kimeríti a limitet.

Ebben az esetben küldd el az X-AstroWay-Site-URL fejlécet a webhely címével:

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

Mód	Limit
Fejléc nélkül	30 kérés / óra IP-nként; a `/v1/embed/*` widgetek külön 120 / óra IP-nként
Fejléccel	300 kérés / óra webhelyenként, maximum 600 / óra IP-nként

A fejléc engedélyezett a CORS-ban, és nem hitelesítő adat, ezért az IP-nkénti korlát megmarad: függetlenül attól, hogy hány domaint neveznek meg egy címről, összesen legfeljebb 600 kérés érkezhet onnan óránként. Mindkét számlálóra egyszerre van szükség: a webhely számlálója akkor aktiválódik, ha egy webhely több címről (CDN, terheléselosztó) érkezik, az IP számlálója pedig akkor, ha egy címről sok név érkezik.

Egy hívás nem mindig egy egység. Egy erőforrás-igényes nyilvános végpont többet fogyaszt ugyanabból a kosárból, nem pedig külön kosarat kap. A POST /v1/public/synastry 3-ba kerül, mert két térképet és egy 45 cellás aspektusmátrixot tartalmaz: a gyakorlati felső határ ehhez 10 óránként be nem jelentett címről, 100 bejelentett webhelyről és 200 címről. Minden más 1-be kerül. Ha egy hívás többe kerül, mint egy egység, a válasz az X-RateLimit-Cost fejlécben jelzi ezt, és a hívás, amely többe kerül, mint amennyi a kosárban maradt, elutasításra kerül, nem pedig mínuszba megy.

Melyik számláló a legszűkebb jelenleg, azt az X-RateLimit-Scope (ip vagy site) válaszfejléc jelzi. A többi X-RateLimit-* fejléc csak ezt írja le, azaz csak az egyik számlálót a kettő közül. A másikat az X-RateLimit-Counters fejlécben láthatod:

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

A formátum: scope=maradék/limit vesszővel elválasztva. A fejléc csak akkor érkezik, ha valóban két számláló van: egy anonim hívás X-AstroWay-Site-URL fejlécvel. A fizetős kulccsal történő hívás a kulcsod és a tarifád alapján kerül elszámolásra, ott egy számláló van, és nincs fejléc. Olvasd el, ha több domaint renderelsz egy címről a szerverről: minden domainnek saját webhelykosara van, de az IP-nkénti korlát közös, és ez ütközik először.

Gyorsítótárazd a válaszokat a saját oldaladon: a napi horoszkóp nem változik a nap folyamán, és az éjfélig tartó gyorsítótár teljesen megoldja a limit problémáját.

Fizetős kulcs nyilvános végpontokon. A /v1/public/* és /v1/embed/* kulcs nélkül is működik, de ha átadod (X-Api-Key), a kérés a tarifád alapján kerül elszámolásra, nem az anonim kvóta alapján, és a válaszban nem lesz ingyenes vízjel. Ennek szerveroldali renderelés esetén van értelme: egy gép kezeli az összes látogatót, és az anonim 300/óra kevés neki.

Költségtáblázat

Teljesen átlátható táblázat az összes 771+ végponttal és azok költségével – a Végpontok költsége oldalon található. A DivineAPI/AstrologyAPI/Prokerala nem tesz közzé ilyen táblázatot. Rövid útmutató:

Szint	Kreditek	Tipikus idő	Példák
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	néhány s	`/rectification/trutine`
6	500	akár 120 s	`/rectification`

Válaszfejlécek

Minden válasz tartalmazza:

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: mennyit vontak le ebből a kérésből
X-Credits-Remaining: maradék a havi keretből
X-Credits-Limit: teljes havi kreditkeret (csomag szerint)
X-Credits-Reset: ISO-8601 dátum az egyenleg frissítéséről
X-RateLimit-*: a csúszó ablak aktuális állapota (standard formátum)
- X-RateLimit-Scope: melyik számláló a legszűkebb jelenleg: ip, site vagy key. A key érték azt jelenti, hogy a kérés a kulcsod és a tarifád limitje alapján került elszámolásra, nem pedig az anonim kvóta alapján.
- X-RateLimit-Counters: nyilvános végponton, X-AstroWay-Site-URL fejlécvel hívva, az összes számláló, amely alapján a kérés elszámolásra került, scope=maradék/limit formátumban. A fenti fejlécek csak a legszűkebbet írják le.
- X-RateLimit-Reset: az a pillanat, amikor a legrégebbi kérés kiesik az ablakból, azaz amikor egy slot felszabadul. Ez nem a teljes bucket megnyitásának ideje: utána egy kérés áthalad, és a Reset a következő időpontra tolódik. Az a kliens, amelyik a Reset-ig vár, majd egy csomagot küld, ismét 429-et kap, ezért megbízhatóbb egyenként küldeni a kéréseket, vagy gyorsítótárazni a válaszokat a saját oldaladon.
- Az elutasított kérés (429) nem fogyaszt kvótát és nem tolja el az ablakot: a számláló csak sikeres kérésekkel töltődik fel.
- X-RateLimit-Origin-Limit és X-RateLimit-Origin-Remaining: csak akkor érkeznek, ha a kérés az engedélyezett források listájának egy bejegyzése alapján történt, és az adott bejegyzéshez rendelt részt mutatják. Az ezen a részen belüli elutasítás szintén 429, és a szövegben megnevezésre kerül, melyik bejegyzés merült ki.
X-Subscription-Status és X-Subscription-Grace-Ends: csak akkor érkeznek, ha a fizetett időszak már lejárt, de a 3 napos türelmi időszak még tart (X-Subscription-Status: grace). A kérések a tarifád szerint kerülnek kiszolgálásra az X-Subscription-Grace-Ends időpontig, utána a válasz 402 SUBSCRIPTION_EXPIRED lesz. Ha a kliensed naplózza a fejléceket, ez a legkorábbi jelzés arra, hogy ideje meghosszabbítani a csomagot.
X-Request-Id: kérésazonosító, 32 hexadecimális karakter; add meg, ha támogatást kérsz.

Mennyit költöttél már: három módszer

A jelenlegi kredit egyenlegedet háromféleképpen ellenőrizheted – a leggyorsabbtól a leg részletesebbig:

Minden válaszban: az X-Credits-Remaining / X-Credits-Used / X-Credits-Limit fejlécek bármely kérésre (még hibára is) visszatérnek. Semmi extrát nem kell hívnod – az egyenleg mindig a szemed előtt van.
Külön kéréssel: a GET /v1/keys/usage a saját X-Api-Key kulcsoddal visszaadja a credits (felhasznált / maradék / limit / reset), a usage (kérések ma / héten / hónapban) és a top 20 végpontot 30 napra. Egy hívás, külön admin-kulcs nélkül.
A műszerfalon: az api.astroway.info/dashboard/billing valós időben mutatja az egyenleget, a használati grafikont és a végpontok szerinti bontást.

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

Gyorsítótárazás

Az azonos kérések 5 percen belül a gyorsítótárból kerülnek visszaadásra kredit levonása nélkül. Ez egy külön fejléc:

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

Mi számít “azonosnak”:

Ugyanaz a végpont
Ugyanaz a JSON body (bájt-bájtra, szóközök normalizálása után)
Ugyanaz az API kulcs

Ez biztonságos, mert minden végpont determinisztikus – azonos bemenet mindig azonos kimenetet eredményez.

Streaming és webhookok

Streaming (`/stream/*`)

10 stream végpont Tier 1: 10 kredit hívásonként díjszabás alá esik. Minden hívás újraszámolja a bolygók pozícióit, ezért ez egy teljes értékű számítás, nem pedig gyorsítótárazott keresés – nincs külön “olcsóbb” díj a tickenkénti lekérdezésre.

Minden válasz két mezőt tartalmaz a takarékos lekérdezéshez:

tickSeconds: ajánlott lekérdezési intervallum;
nextEventAt: mikor változik meg az állapot legközelebb.

A tickSeconds-nél gyakrabban lekérdezni felesleges kreditpazarlás: az állapot nem változik meg a nextEventAt időpontig.

Webhookok (`/webhooks/*`)

Az előfizetés-kezelési CRUD műveletek (/webhooks/subscribe, lista, megtekintés, törlés, /test) Tier 1: 10 kreditbe kerülnek darabonként. Ezek ritka hívások.

Az események kézbesítése (szerver → a te URL-ed) nem kerül díjazásra: a kreditek csak a CRUD-kezelési hívásokért kerülnek levonásra. 12 eseménytípus támogatott (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress stb.).

A webhookok Pro és magasabb csomagoktól érhetők el.

Mit tegyél, ha túlléped a limiteket

`402 Payment Required`: elfogytak a kreditek

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

Lehetőségek:

Csomagfrissítés: azonnal új keretet kapsz
Overage (Starter/Pro): automatikusan bekapcsol, ha nincs kikapcsolva a beállításokban
Várni a resetre (Free): a következő hónap 1. napja

`429 Too Many Requests`: túllépve az RPM-et

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

A Retry-After: 12 fejléc egy szabványos HTTP-fejléc, a HTTP-kliensednek értenie kell.

Helyes kezelés:

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

Költségvetés előzetes becslése

Integráció előtt becsüld meg, mennyi kreditre lesz szükséged havonta:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Példa: egy alkalmazás 500 DAU-val, minden felhasználó napi 3 térkép számítást + 1 szinasztriát végez:

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

Költségvetés kalkulátor – a Díjszabás oldalon.

Tovább

Hibák: teljes hibakód-referencia
Idempotencia: hogyan küldj biztonságosan ismételt kéréseket

Hasznos volt?

Javítás javaslata

Utoljára frissítve: 2026. okt. 5.

// Előző

Gematria és a 72 név

Következő //

Végpontonkénti költség