Credite și limite

AstroWay folosește un model de credit în loc de un simplu contor de cereri.

Este mai echitabil: endpoint-urile ușoare (/planets) costă 10 credite, cele grele (/rectification) - 500.

Două tipuri de limite

1. Buget zilnic/lunar de credite

Numărul de credite pe lună depinde de plan:

Plan	Credite/lună	Limită zilnică
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

Imediat ce creditele sunt epuizate - cererile ulterioare returnează 402 Payment Required (Free) sau declanșează facturarea overage (Indie+).

2. Limită de rată (cereri pe minut)

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

Limita de rată - fereastră glisantă. Dacă ai trimis 120 de cereri în 10 secunde, următoarele 50 de secunde pe această cheie - 429.

Dacă o cheie are o listă de origini permise, fiecare intrare din listă primește o parte din această limită: limita cheii împărțită la numărul de intrări, rotunjită în sus. Un singur site cu un widget încorporat nu poate, din această cauză, să consume cota pentru care plătește proprietarul cheii, iar celelalte domenii ale sale rămân funcționale. Limita totală a cheii nu crește: părțile o împart, nu se adaugă la ea.

Contorul este menținut exact pentru intrare, nu pentru host-ul care a venit. Intrarea *.example.com este un singur contor pentru toate subdomeniile, altfel restricția ar fi ocolită prin inventarea unui nou subdomeniu pentru fiecare cerere. Când există o singură intrare în listă, partea este egală cu limita și nimic nu se schimbă.

3. Endpoint-uri publice (fără cheie)

14 dicționare de referință /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) sunt servite public, fără X-Api-Key și costă 0 credite. Limita este de 30 de cereri / oră de la o singură adresă IP. Aceleași date sunt expuse ca Resurse MCP astroway://reference/<slug> pentru agenții LLM.

Aceeași limită se aplică și pentru restul namespace-urilor publice: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Cotă pentru randare pe server

30 de cereri pe oră sunt calculate pentru browser: fiecare vizitator aduce propria adresă IP și propria cotă. Dacă cererile sunt făcute de serverul tău (plugin WordPress, SSR, preîncărcare cache), o singură adresă servește toți vizitatorii și epuizează limita în câteva reîncărcări de pagină.

Pentru acest caz, trimite antetul X-AstroWay-Site-URL cu adresa site-ului:

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

Mod	Limită
Fără antet	30 cereri / oră pe IP; widget-urile `/v1/embed/*` au o limită separată de 120 / oră pe IP
Cu antet	300 cereri / oră pe site, plafon 600 / oră pe IP

Antetul este permis în CORS și nu reprezintă credențiale, de aceea plafonul pe IP rămâne: indiferent câte domenii ar fi numite de la o singură adresă, în total de acolo nu vor pleca mai mult de 600 de cereri pe oră. Ambele contoare sunt necesare simultan: contorul site-ului se activează când un site accesează de la mai multe adrese (CDN, load balancer), contorul IP se activează când de la o singură adresă vin multe nume.

Un singur apel nu este întotdeauna o singură unitate. Un endpoint public greu consumă mai mult din același coș, nu primește unul separat. POST /v1/public/synastry costă 3, deoarece sunt două hărți și o matrice de aspecte de 45 de celule: plafonul practic pentru acesta este de 10 pe oră de la o adresă nedeclarată, 100 pe site-ul declarat și 200 pe adresă. Toate celelalte costă 1. Când un apel costă mai mult decât o unitate, răspunsul indică acest lucru în antetul X-RateLimit-Cost, iar un apel care costă mai mult decât a rămas în coș este respins, nu intră în minus.

Antetul răspunsului X-RateLimit-Scope (ip sau site) indică care contor este cel mai restrictiv în prezent. Restul antetelor X-RateLimit-* îl descriu pe acesta, adică doar unul dintre cele două contoare. Al doilea este vizibil în X-RateLimit-Counters:

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

Formatul este scope=rămas/limită separat prin virgulă. Antetul apare doar atunci când există într-adevăr două contoare: un apel anonim cu X-AstroWay-Site-URL. Un apel cu o cheie plătită este contorizat conform cheii și tarifului tău, acolo contorul este unul singur și antetul nu există. Citește-l dacă randezi de pe server mai multe domenii de la o singură adresă: coșul site-ului este propriu fiecărui domeniu, dar plafonul pe IP este comun, și acesta este cel care se atinge primul.

Cachează răspunsurile pe partea ta: horoscopul zilnic nu se schimbă pe parcursul zilei, iar un cache până la miezul nopții rezolvă complet problema limitei.

Cheie plătită pe endpoint-uri publice. /v1/public/* și /v1/embed/* funcționează fără cheie, dar dacă o transmiți (X-Api-Key), cererea este contorizată conform tarifului tău, nu conform cotei anonime, și răspunsul nu conține filigranul gratuit. Acest lucru are sens pentru randarea server-side: o singură mașină accesează pentru toți vizitatorii, iar 300/oră anonime sunt insuficiente pentru ea.

Tabelul de costuri

Tabelul complet și transparent cu toate cele 771+ endpoint-uri și costul lor - pe pagina Costul endpoint-urilor. DivineAPI/AstrologyAPI/Prokerala nu publică un astfel de tabel. O referință rapidă:

Nivel	Credite	Timp tipic	Exemple
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	câteva s	`/rectification/trutine`
6	500	până la 120 s	`/rectification`

Antetele răspunsului

Fiecare răspuns conține:

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: cât a fost debitat pentru această cerere
X-Credits-Remaining: soldul rămas din bugetul lunar
X-Credits-Limit: bugetul total de credite pe lună (conform planului)
X-Credits-Reset: data ISO-8601 de reîmprospătare a soldului
X-RateLimit-*: starea curentă a ferestrei glisante (format standard)
- X-RateLimit-Scope: care contor este cel mai restrictiv în prezent: ip, site sau key. Valoarea key înseamnă că cererea a fost contorizată conform cheii tale și limitei tarifului tău, nu conform cotei anonime.
- X-RateLimit-Counters: pe un endpoint public, apelat cu X-AstroWay-Site-URL, toate contoarele după care a fost contorizată cererea, în formatul scope=rămas/limită. Antetele de mai sus descriu doar cel mai restrictiv.
- X-RateLimit-Reset: momentul când cea mai veche cerere va ieși din fereastră, adică când se va elibera un slot. Acesta nu este momentul deschiderii complete a bucket-ului: după el va trece o cerere, iar Reset se va muta la următoarea în timp. Un client care așteaptă până la Reset și apoi trimite un pachet, va primi din nou 429, de aceea este mai sigur să trimiți o singură cerere sau să cachezi răspunsurile pe partea ta.
- O cerere respinsă (429) nu consumă cotă și nu deplasează fereastra: contorul se reîncarcă doar cu cereri reușite.
- X-RateLimit-Origin-Limit și X-RateLimit-Origin-Remaining: apar doar atunci când cererea a trecut conform unei intrări din lista de origini permise și arată partea alocată exact acestei intrări. Refuzul pentru această parte este de asemenea 429, iar în text este menționat ce intrare a fost epuizată.
X-Subscription-Status și X-Subscription-Grace-Ends: apar doar atunci când perioada plătită s-a încheiat deja, iar perioada de grație de 3 zile este încă în desfășurare (X-Subscription-Status: grace). Cererile sunt servite conform tarifului tău până la momentul din X-Subscription-Grace-Ends, după acesta răspunsul este 402 SUBSCRIPTION_EXPIRED. Dacă clientul tău înregistrează antetele, acesta este cel mai timpuriu semnal că este timpul să prelungești planul.
X-Request-Id: identificatorul cererii, 32 caractere hexadecimale; menționează-l când contactezi suportul

Cât s-a cheltuit deja: trei metode

Poți verifica soldul curent de credite în trei moduri - de la cel mai rapid la cel mai detaliat:

În fiecare răspuns: antetele X-Credits-Remaining / X-Credits-Used / X-Credits-Limit sunt returnate la orice cerere (chiar și la eroare). Nu este nevoie să apelezi nimic suplimentar - soldul este întotdeauna la vedere.
Printr-o cerere separată: GET /v1/keys/usage cu X-Api-Key-ul tău returnează credits (used / remaining / limit / reset), usage (cereri pentru today / week / month) și top-20 endpoint-uri pe 30 de zile. Un singur apel, fără o cheie admin separată.
În tabloul de bord: api.astroway.info/dashboard/billing arată soldul, graficul de utilizare și defalcarea pe endpoint-uri în timp real.

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

Caching

Cererile identice în decurs de 5 minute sunt returnate din cache fără debitarea creditelor. Acesta este un antet separat:

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

Ce se consideră “identic”:

Același endpoint
Același corp JSON (byte-cu-byte după normalizarea spațiilor)
Aceeași cheie API

Acest lucru este sigur, deoarece toate endpoint-urile sunt deterministe - aceeași intrare dă întotdeauna aceeași ieșire.

Streaming și webhook-uri

Streaming (`/stream/*`)

10 endpoint-uri de streaming sunt tarifate ca Nivel 1: 10 credite per apel. Fiecare apel recalculează pozițiile planetelor, deci este o calculare completă, nu o căutare cache-uită - nu există o rată “mai ieftină” separată per tick.

Fiecare răspuns conține două câmpuri pentru interogare economică:

tickSeconds: intervalul de interogare recomandat;
nextEventAt: când se va schimba starea data viitoare.

Interogarea mai frecventă decât tickSeconds înseamnă arderea inutilă a creditelor: starea nu se va schimba până la nextEventAt.

Webhook-uri (`/webhooks/*`)

Operațiunile CRUD de gestionare a abonamentului (/webhooks/subscribe, listare, vizualizare, ștergere, /test) costă Nivel 1: 10 credite fiecare. Acestea sunt apeluri rare.

Livrarea evenimentelor (server → URL-ul tău) nu este tarifată: creditele sunt debitate doar pentru apelurile CRUD de gestionare. Sunt suportate 12 tipuri de evenimente (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress etc.).

Webhook-urile sunt disponibile începând cu planul Pro și superior.

Ce să faci în caz de depășire a limitelor

`402 Payment Required`: credite epuizate

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

Opțiuni:

Upgrade plan: primești imediat un buget nou
Overage (Starter/Pro): se activează automat, dacă nu este dezactivat în settings
Așteaptă resetarea (Free): 1 a lunii următoare

`429 Too Many Requests`: RPM depășit

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

Antetul Retry-After: 12 - un antet HTTP standard, clientul tău HTTP ar trebui să-l înțeleagă.

Gestionare corectă:

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

Estimarea bugetului în avans

Înainte de integrare, estimează câte credite ai nevoie pe lună:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Exemplu: o aplicație cu 500 DAU, fiecare utilizator face 3 calcule de hărți + 1 sinastrie pe zi:

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

Calculatorul de buget - pe pagina Tarife.

Mai departe

Erori: ghid complet de coduri de eroare
Idempotency: cum să faci cereri repetate în siguranță

Util?

Sugerează o corectură

Ultima actualizare: 5 oct. 2026

// Pagina precendentă

Gematria și cele 72 de nume

Pagina următoare //

Cost per endpoint