Kredity a limity

AstroWay používá kreditový model namísto jednoduchého počítadla požadavků.

Získejte API klíč za 60 sekund

aw_test_demo_aaaa1111

Zaregistrovat se – zdarma→

Je to spravedlivější: lehké endpointy (/planets) stojí 10 kreditů, náročné (/rectification) – 500.

Dva typy limitů

1. Denní/měsíční rozpočet kreditů

Počet kreditů za měsíc závisí na plánu:

Plán	Kreditů/měsíc	Denní 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

Jakmile jsou kredity vyčerpány – následující požadavky vrátí 402 Payment Required (Free) nebo spustí overage-účtování (Indie+).

2. Rate limit (požadavků za minutu)

Plán	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. Pokud jsi vystřelil 120 požadavků za 10 sekund, následujících 50 sekund na tomto klíči – 429.

Tip

Rate limit a kreditový rozpočet jsou nezávislé. Můžeš mít kredity, ale neprojít rate limit. A naopak.

Pokud má klíč seznam povolených původů, každý záznam seznamu obdrží svůj podíl z tohoto limitu: limit klíče je rozdělen počtem záznamů, zaokrouhleno nahoru. Jeden web s vloženým widgetem nemůže kvůli tomu spotřebovat kvótu, za kterou platí vlastník klíče, a ostatní jeho domény zůstanou funkční. Celkový limit klíče neroste: podíly ho dělí, nikoli k němu přidávají.

Počítadlo se vede právě podle záznamu, nikoli podle hosta, který přišel. Záznam *.example.com je jedno počítadlo pro všechny subdomény, jinak by se omezení obcházelo vymýšlením nové subdomény pro každý požadavek. Když je v seznamu jeden záznam, podíl se rovná limitu a nic se nemění.

3. Veřejné endpointy (bez klíče)

14 referenčních slovníků /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) je obsluhováno veřejně, bez X-Api-Key a stojí 0 kreditů. Omezení – 30 požadavků / hodinu z jedné IP adresy. Stejná data jsou vystavena jako MCP Resources astroway://reference/<slug> pro LLM agenty.

Stejný limit platí pro zbytek veřejných jmenných prostorů: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Kvóta pro renderování na serveru

30 požadavků za hodinu je určeno pro prohlížeč: každý návštěvník přináší vlastní IP a vlastní kvótu. Pokud však požadavky provádí tvůj server (WordPress plugin, SSR, předehřívání keše), jedna adresa obsluhuje všechny návštěvníky a vyčerpá limit za několik opětovných načtení stránky.

Pro tento případ odešli hlavičku X-AstroWay-Site-URL s adresou webu:

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

Režim	Limit
Bez hlavičky	30 požadavků / hodinu na IP; widgety /v1/embed/* mají samostatných 120 / hodinu na IP
S hlavičkou	300 požadavků / hodinu na web, strop 600 / hodinu na IP

Hlavička je povolena v CORS a není přihlašovacími údaji, proto strop na IP zůstává: kolik domén bys z jedné adresy nenazval, celkově odtud odejde ne více než 600 požadavků za hodinu. Obě počítadla jsou potřeba současně: počítadlo webu se aktivuje, když jeden web přistupuje z mnoha adres (CDN, load balancer), počítadlo IP se aktivuje, když z jedné adresy přichází mnoho jmen.

Jedno volání není vždy jedna jednotka. Náročný veřejný endpoint spotřebuje více ze stejného koše, nikoli samostatný. POST /v1/public/synastry stojí 3, protože to jsou dvě mapy a matice aspektů o 45 buňkách: praktický strop pro něj je 10 za hodinu z neohlášené adresy, 100 na ohlášený web a 200 na adresu. Vše ostatní stojí 1. Když volání stojí více než jednu jednotku, odpověď to sdělí v hlavičce X-RateLimit-Cost, a volání, které stojí více, než zbylo v koši, je odmítnuto, nikoli jde do mínusu.

Které počítadlo je aktuálně nejtěsnější, sděluje hlavička odpovědi X-RateLimit-Scope (ip nebo site). Zbytek hlaviček X-RateLimit-* popisuje právě jej, tedy pouze jedno počítadlo ze dvou. Druhé je vidět v X-RateLimit-Counters:

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

Formát – scope=zbytek/limit oddělený čárkou. Hlavička přichází pouze tehdy, když jsou skutečně dvě počítadla: anonymní volání s X-AstroWay-Site-URL. Volání s placeným klíčem se počítá podle klíče a podle tvého tarifu, tam je počítadlo jedno a hlavička chybí. Čti ji, pokud renderuješ ze serveru několik domén z jedné adresy: koš webu má každá doména svůj, ale strop na IP je společný, a právě ten se vyčerpá jako první.

Kešuj odpovědi na své straně: denní horoskop se během dne nemění, a keš do půlnoci zcela řeší otázku limitu.

Placený klíč na veřejných endpointech. /v1/public/* a /v1/embed/* fungují bez klíče, ale pokud ho předáš (X-Api-Key), požadavek se počítá podle tvého tarifu, nikoli podle anonymní kvóty, a v odpovědi není bezplatný vodoznak. To dává smysl pro server-side renderování: jeden stroj obsluhuje všechny návštěvníky, a anonymních 300/hod je pro něj málo.

Tabulka nákladů

Úplná transparentní tabulka se všemi 771+ endpointy a jejich náklady – na stránce Náklady na endpointy. DivineAPI/AstrologyAPI/Prokerala takovou tabulku nepublikují. Stručný přehled:

Tier	Kreditů	Typický čas	Příklady
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ěkolik s	/rectification/trutine
6	500	až 120 s	/rectification

Hlavičky odpovědi

Každá odpověď obsahuje:

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: kolik bylo strženo za tento požadavek
• X-Credits-Remaining: zbytek z měsíčního rozpočtu
• X-Credits-Limit: celkový rozpočet kreditů za měsíc (dle plánu)
• X-Credits-Reset: ISO-8601 datum obnovení zůstatku
• X-RateLimit-*: aktuální stav sliding window (standardní formát)
  • X-RateLimit-Scope: které počítadlo je aktuálně nejtěsnější: ip, site nebo key. Hodnota key znamená, že požadavek byl započítán podle tvého klíče a podle limitu tvého tarifu, nikoli podle anonymní kvóty.
  • X-RateLimit-Counters: na veřejném endpointu, volaném s X-AstroWay-Site-URL, všechna počítadla, podle kterých byl požadavek započítán, ve formátu scope=zbytek/limit. Hlavičky výše popisují pouze nejtěsnější.
  • X-RateLimit-Reset: okamžik, kdy z okna vypadne nejstarší požadavek, tedy kdy se uvolní jeden slot. To není čas úplného otevření bucketu: po něm projde jeden požadavek, a Reset se posune na další v čase. Klient, který čeká do Reset a pak pošle dávku, opět obdrží 429, proto je spolehlivější jít po jednom požadavku nebo kešovat odpovědi na své straně.
  • Odmítnutý požadavek (429) kvótu nespotřebovává a okno neposouvá: počítadlo se doplňuje pouze úspěšnými požadavky.
  • X-RateLimit-Origin-Limit a X-RateLimit-Origin-Remaining: přicházejí pouze tehdy, když požadavek prošel podle záznamu ze seznamu povolených původů, a ukazují podíl, přidělený právě tomuto záznamu. Odmítnutí kvůli tomuto podílu je také 429, a v textu je uvedeno, který záznam byl vyčerpán.
• X-Subscription-Status a X-Subscription-Grace-Ends: přicházejí pouze tehdy, když placené období již skončilo, a 3denní grace period ještě trvá (X-Subscription-Status: grace). Požadavky jsou obsluhovány podle tvého tarifu do okamžiku v X-Subscription-Grace-Ends, po něm odpověď 402 SUBSCRIPTION_EXPIRED. Pokud tvůj klient loguje hlavičky, je to nejčasnější signál, že je čas plán prodloužit.
• X-Request-Id: identifikátor požadavku, 32 šestnáctkových znaků; uveď ho při kontaktování podpory

Kolik už bylo utraceno: tři způsoby

Zkontrolovat aktuální zůstatek kreditů můžeš třemi způsoby – od nejrychlejšího po nejpodrobnější:

1. V každé odpovědi: hlavičky X-Credits-Remaining / X-Credits-Used / X-Credits-Limit se vrací na jakýkoli požadavek (i na chybu). Nic dalšího volat nemusíš – zůstatek je vždy před očima.
2. Samostatným požadavkem: GET /v1/keys/usage se svým X-Api-Key vrací credits (used / remaining / limit / reset), usage (požadavků za today / week / month) a top 20 endpointů za 30 dní. Jedno volání, bez samostatného admin klíče.
3. V dashboardu: api.astroway.info/dashboard/billing ukazuje zůstatek, graf usage a rozdělení podle endpointů v reálném čase.

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

Tip

Na rozdíl od většiny API (Anthropic, OpenAI) vrací AstroWay zbytek zůstatku přímo v hlavičce každé odpovědi (X-Credits-Remaining) – nemusíš chodit do dashboardu ani do samostatného usage-API, abys zjistil, kolik zbylo.

Kešování

Identické požadavky během 5 minut se vrací z keše bez stržení kreditů. To je samostatná hlavička:

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

Co se považuje za “identické”:

• Stejný endpoint
• Stejný JSON body (byte-by-byte po normalizaci mezer)
• Stejný API klíč

To je bezpečné, protože všechny endpointy jsou deterministické – stejný input vždy dává stejný output.

Streamování a webhooky

Streamování (/stream/*)

10 stream endpointů je tarifováno jako Tier 1: 10 kreditů za volání. Každé volání přepočítává pozice planet, proto je to plnohodnotný výpočet, nikoli kešovaný lookup – samostatná “levnější” sazba za tick neexistuje.

Každá odpověď obsahuje dvě pole pro úsporné dotazování:

• tickSeconds: doporučený interval dotazování;
• nextEventAt: kdy se stav změní příště.

Dotazovat se častěji než tickSeconds – zbytečně pálit kredity: stav se nezmění do nextEventAt.

Upozornění

Příklad rozpočtu: jeden stream, dotazovaný každých 60 s = 1 440 volání/den × 10 kreditů = 14 400 kreditů/den. Na Indie (50 000/měsíc) to jsou ~3.5 dne jednoho streamu. Pro neustálé streamování – Starter+.

Webhooky (/webhooks/*)

CRUD operace správy předplatného (/webhooks/subscribe, seznam, prohlížení, mazání, /test) stojí Tier 1: 10 kreditů každá. To jsou vzácná volání.

Doručení události (server → tvá URL) není tarifováno: kredity se strhávají pouze za CRUD volání správy. Podporováno je 12 typů událostí (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress atd.).

Webhooky jsou dostupné od plánu Pro a vyšší.

Co dělat při překročení limitů

402 Payment Required: došly kredity

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

Možnosti:

• Upgrade plánu: okamžitě získáš nový rozpočet
• Overage (Starter/Pro): zapíná se automaticky, pokud není vypnuto v settings
• Čekat na reset (Free): 1. den následujícího měsíce

429 Too Many Requests: překročeno RPM

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

Hlavička Retry-After: 12 – standardní HTTP hlavička, tvůj HTTP klient by ji měl rozumět.

Správné zpracování:

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

Upozornění

Nedělej exponenciální backoff bez cap – Retry-After v odpovědi již obsahuje přesné číslo. Důvěřuj mu.

Odhad rozpočtu předem

Před integrací si odhadni, kolik kreditů potřebuješ za měsíc:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Příklad: aplikace s 500 DAU, každý uživatel provede 3 výpočty map + 1 synastrii denně:

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

Kalkulátor rozpočtu – na stránce Tarify.

Dále

• Chyby: úplný referenční průvodce error kódy
• Idempotence: jak provádět opakované požadavky bezpečně