Credits en limieten

AstroWay gebruikt een creditmodel in plaats van een eenvoudige verzoekenteller.

Krijg een API-sleutel in 60 seconden

aw_test_demo_aaaa1111

Aanmelden - gratis→

Dit is eerlijker: lichte endpoints (/planets) kosten 10 credits, zware (/rectification) - 500.

Twee soorten limieten

1. Dagelijks/maandelijks creditbudget

Het aantal credits per maand is afhankelijk van het plan:

Plan	Credits/maand	Dagelijkse limiet
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

Zodra de credits op zijn, retourneren volgende verzoeken 402 Payment Required (Free) of activeren overage-facturering (Indie+).

2. Rate limit (verzoeken per minuut)

Plan	RPM
Free	10 verzoeken/min
Indie	30 verzoeken/min
Starter	120 verzoeken/min
Pro	400 verzoeken/min
Business	1.000 verzoeken/min
Enterprise	Custom

De rate limit is een sliding window. Als je 120 verzoeken in 10 seconden hebt afgevuurd, zijn de volgende 50 seconden op deze sleutel 429.

Tip

Rate limit en creditbudget zijn onafhankelijk. Je kunt credits hebben, maar de rate limit niet halen. En vice versa.

Als een sleutel een lijst met toegestane herkomsten heeft, krijgt elk item in de lijst zijn deel van deze limiet: de sleutellimiet gedeeld door het aantal items, naar boven afgerond. Eén website met een ingebedde widget kan hierdoor niet het quotum opeten waarvoor de sleuteleigenaar betaalt, terwijl zijn andere domeinen operationeel blijven. De totale sleutellimiet groeit niet: de delen verdelen deze, ze worden er niet bij opgeteld.

De teller wordt bijgehouden per item, niet per inkomende host. Het item *.example.com is één teller voor alle subdomeinen, anders zou de beperking omzeild kunnen worden door voor elk verzoek een nieuw subdomein te verzinnen. Als er één item in de lijst staat, is het deel gelijk aan de limiet en verandert er niets.

3. Publieke endpoints (zonder sleutel)

14 referentiewoordenboeken /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) worden publiekelijk, zonder X-Api-Key aangeboden en kosten 0 credits. De limiet is 30 verzoeken / uur vanaf één IP. Deze gegevens zijn ook beschikbaar als MCP Resources astroway://reference/<slug> voor LLM-agenten.

Dezelfde limiet geldt voor de rest van de publieke namespaces: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Quotum voor server-side rendering

30 verzoeken per uur zijn berekend voor de browser: elke bezoeker brengt zijn eigen IP en eigen quotum mee. Als jouw server de verzoeken doet (WordPress-plugin, SSR, cache-warming), gaat één adres voor alle bezoekers en verbruikt de limiet in een paar paginabladwijzers.

Stuur in dit geval de header X-AstroWay-Site-URL met het websiteadres mee:

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

Modus	Limiet
Zonder header	30 verzoeken / uur per IP; widgets /v1/embed/* hebben aparte 120 / uur per IP
Met header	300 verzoeken / uur per website, plafond 600 / uur per IP

De header is toegestaan in CORS en is geen authenticatiegegeven, daarom blijft het IP-plafond bestaan: hoeveel domeinen je ook vanaf één adres noemt, er zullen in totaal niet meer dan 600 verzoeken per uur vandaan komen. Beide tellers zijn tegelijkertijd nodig: de websiteteller werkt wanneer één website vanaf meerdere adressen komt (CDN, load balancer), de IP-teller werkt wanneer veel namen vanaf één adres komen.

Eén aanroep is niet altijd één eenheid. Een zwaar publiek endpoint verbruikt meer van hetzelfde mandje, en krijgt geen apart mandje. POST /v1/public/synastry kost 3, want het zijn twee kaarten en een aspectmatrix van 45 cellen: het praktische plafond hiervoor is 10 per uur vanaf een niet-aangegeven adres, 100 voor een aangegeven website en 200 per adres. Al het andere kost 1. Wanneer een aanroep meer dan één eenheid kost, vermeldt het antwoord dit in de header X-RateLimit-Cost, en een aanroep die meer kost dan er in het mandje over is, wordt geweigerd in plaats van in de min te gaan.

Welke teller momenteel het meest beperkend is, wordt aangegeven door de X-RateLimit-Scope header (ip of site). De overige X-RateLimit-* headers beschrijven alleen deze, dus slechts één van de twee tellers. De tweede is zichtbaar in X-RateLimit-Counters:

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

Formaat - scope=resterend/limiet gescheiden door komma’s. De header wordt alleen verzonden als er daadwerkelijk twee tellers zijn: een anonieme aanroep met X-AstroWay-Site-URL. Een aanroep met een betaalde sleutel wordt geteld op basis van jouw sleutel en jouw tarief, daar is maar één teller en geen header. Lees deze als je vanaf de server meerdere domeinen vanaf één adres rendert: het websitemandje is voor elk domein anders, maar het IP-plafond is gemeenschappelijk, en dat is het eerste dat wordt bereikt.

Cache de antwoorden aan jouw kant: een dagelijkse horoscoop verandert niet gedurende de dag, en een cache tot middernacht lost de limietkwestie volledig op.

Betaalde sleutel op publieke endpoints. /v1/public/* en /v1/embed/* werken zonder sleutel, maar als je deze meestuurt (X-Api-Key), wordt het verzoek geteld op basis van jouw tarief, en niet op basis van het anonieme quotum, en het antwoord bevat geen gratis watermerk. Dit is zinvol voor server-side rendering: één machine gaat voor alle bezoekers, en anonieme 300/uur is te weinig voor haar.

Kostentabel

Een volledige transparante tabel met alle 771+ endpoints en hun kosten - op de pagina Endpointkosten. DivineAPI/AstrologyAPI/Prokerala publiceren zo’n tabel niet. Korte richtlijn:

Tier	Credits	Typische tijd	Voorbeelden
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	enkele s	/rectification/trutine
6	500	tot 120 s	/rectification

Antwoordheaders

Elk antwoord bevat:

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: hoeveel is afgeschreven voor dit verzoek
• X-Credits-Remaining: resterend op het maandelijkse budget
• X-Credits-Limit: volledig creditbudget per maand (volgens plan)
• X-Credits-Reset: ISO-8601 datum van saldo-update
• X-RateLimit-*: huidige status van het sliding window (standaard formaat)
  • X-RateLimit-Scope: welke teller momenteel het meest beperkend is: ip, site of key. De waarde key betekent dat het verzoek is geteld op basis van jouw sleutel en de limiet van jouw tarief, en niet op basis van het anonieme quotum.
  • X-RateLimit-Counters: op een publiek endpoint, aangeroepen met X-AstroWay-Site-URL, alle tellers waartegen het verzoek is geteld, in het formaat scope=resterend/limiet. De bovenstaande headers beschrijven alleen de meest beperkende.
  • X-RateLimit-Reset: het moment waarop het oudste verzoek uit het venster valt, d.w.z. wanneer één slot vrijkomt. Dit is niet het moment van volledige opening van de bucket: daarna zal één verzoek passeren, en Reset zal verschuiven naar de volgende in de tijd. Een client die wacht tot Reset en dan een batch stuurt, krijgt opnieuw 429, daarom is het betrouwbaarder om één verzoek tegelijk te doen of antwoorden aan jouw kant te cachen.
  • Een geweigerd verzoek (429) verbruikt geen quotum en verschuift het venster niet: de teller wordt alleen aangevuld met succesvolle verzoeken.
  • X-RateLimit-Origin-Limit en X-RateLimit-Origin-Remaining: worden alleen verzonden wanneer het verzoek is geslaagd op basis van een item uit de lijst met toegestane herkomsten, en tonen het deel dat specifiek aan dat item is toegewezen. Een weigering op basis van dit deel is ook 429, en de tekst vermeldt welk item is uitgeput.
• X-Subscription-Status en X-Subscription-Grace-Ends: worden alleen verzonden wanneer de betaalde periode al is afgelopen, maar de 3-daagse respijtperiode nog loopt (X-Subscription-Status: grace). Verzoeken worden verwerkt volgens jouw tarief tot het moment in X-Subscription-Grace-Ends, daarna is het antwoord 402 SUBSCRIPTION_EXPIRED. Als jouw client de headers logt, is dit het vroegste signaal dat het tijd is om het plan te verlengen.
• X-Request-Id: verzoek-ID, 32 hexadecimale tekens; vermeld deze bij contact met de ondersteuning

Hoeveel is al verbruikt: drie manieren

Je kunt het huidige creditssaldo op drie manieren controleren - van de snelste tot de meest gedetailleerde:

1. In elk antwoord: de headers X-Credits-Remaining / X-Credits-Used / X-Credits-Limit worden geretourneerd bij elk verzoek (zelfs bij een fout). Je hoeft niets extra’s aan te roepen - het saldo is altijd zichtbaar.
2. Met een apart verzoek: GET /v1/keys/usage met jouw X-Api-Key retourneert credits (gebruikt / resterend / limiet / reset), usage (verzoeken voor vandaag / week / maand) en de top-20 endpoints van de afgelopen 30 dagen. Eén aanroep, zonder aparte admin-sleutel.
3. In het dashboard: api.astroway.info/dashboard/billing toont het saldo, de gebruiksstatistieken en een uitsplitsing per endpoint in realtime.

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

Tip

In tegenstelling tot de meeste API’s (Anthropic, OpenAI), retourneert AstroWay het resterende saldo direct in de header van elk antwoord (X-Credits-Remaining) - je hoeft niet naar het dashboard of een aparte usage-API te gaan om te zien hoeveel er nog over is.

Caching

Identieke verzoeken binnen 5 minuten worden uit de cache geretourneerd zonder creditafschrijving. Dit is een aparte header:

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

Wat wordt beschouwd als “identiek”:

• Hetzelfde endpoint
• Dezelfde JSON body (byte-voor-byte na normalisatie van spaties)
• Dezelfde API-sleutel

Dit is veilig, omdat alle endpoints deterministisch zijn - dezelfde input geeft altijd dezelfde output.

Streaming en webhooks

Streaming (/stream/*)

10 stream-endpoints worden gefactureerd als Tier 1: 10 credits per aanroep. Elke aanroep herberekenent de posities van planeten, dus het is een volledige berekening, geen gecachte lookup - er is geen apart “goedkoper” tarief per tick.

Elk antwoord bevat twee velden voor efficiënte polling:

• tickSeconds: aanbevolen polling-interval;
• nextEventAt: wanneer de status de volgende keer zal veranderen.

Vaker pollen dan tickSeconds is zinloos credits verspillen: de status verandert niet vóór nextEventAt.

Opgepast

Voorbeeld budget: één stream, elke 60 seconden gepolld = 1.440 aanroepen/dag × 10 credits = 14.400 credits/dag. Op Indie (50.000/maand) is dit ~3,5 dagen van één stream. Voor continue streaming - Starter+.

Webhooks (/webhooks/*)

CRUD-operaties voor abonnementsbeheer (/webhooks/subscribe, lijst, bekijken, verwijderen, /test) kosten elk Tier 1: 10 credits. Dit zijn zeldzame aanroepen.

Levering van een event (server → jouw URL) wordt niet gefactureerd: credits worden alleen afgeschreven voor CRUD-beheeraanroepen. 12 soorten events worden ondersteund (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress enz.).

Webhooks zijn beschikbaar vanaf het Pro-plan en hoger.

Wat te doen bij overschrijding van limieten

402 Payment Required: credits op

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

Opties:

• Plan upgraden: je krijgt direct een nieuw budget
• Overage (Starter/Pro): wordt automatisch ingeschakeld, tenzij uitgeschakeld in de instellingen
• Wachten op reset (Free): 1e van de volgende maand

429 Too Many Requests: RPM overschreden

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

De header Retry-After: 12 is een standaard HTTP-header, jouw HTTP-client moet deze begrijpen.

Correcte afhandeling:

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

Opgepast

Doe geen exponentiële backoff zonder cap - Retry-After in het antwoord bevat al het exacte getal. Vertrouw erop.

Budget inschatten van tevoren

Schat vóór de integratie in hoeveel credits je per maand nodig hebt:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Voorbeeld: applicatie met 500 DAU, elke gebruiker doet 3 kaartberekeningen + 1 synastrie per dag:

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

Budgetcalculator - op de pagina Tarieven.

Verder

• Fouten: volledige referentie van errorcodes
• Idempotentie: hoe je herhaalde verzoeken veilig kunt doen