Credits und Limits

AstroWay verwendet ein Kreditmodell anstelle eines einfachen Anfragencounters.

Das ist fairer: Leichte Endpunkte (/planets) kosten 10 Credits, schwere (/rectification) kosten 500.

Zwei Arten von Limits

1. Tägliches/monatliches Kreditbudget

Die Anzahl der Credits pro Monat hängt vom Plan ab:

Plan	Credits/Monat	Tageslimit
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

Sobald die Credits aufgebraucht sind, geben nachfolgende Anfragen 402 Payment Required (Free) zurück oder lösen eine Overage-Abrechnung (Indie+) aus.

2. Rate Limit (Anfragen pro Minute)

Plan	RPM
Free	10 Anfragen/Min
Indie	30 Anfragen/Min
Starter	120 Anfragen/Min
Pro	400 Anfragen/Min
Business	1 000 Anfragen/Min
Enterprise	Custom

Das Rate Limit ist ein Sliding Window. Wenn du 120 Anfragen in 10 Sekunden gesendet hast, erhältst du für die nächsten 50 Sekunden mit diesem Schlüssel 429.

Wenn ein Schlüssel eine Liste zulässiger Ursprünge hat, erhält jeder Listeneintrag seinen Anteil an diesem Limit: Das Schlüssellimit geteilt durch die Anzahl der Einträge, aufgerundet. Eine Website mit einem eingebetteten Widget kann dadurch nicht das gesamte Kontingent aufbrauchen, für das der Schlüsselbesitzer bezahlt, während andere seiner Domains funktionsfähig bleiben. Das Gesamtlimit des Schlüssels erhöht sich nicht: Die Anteile teilen es, anstatt sich zu addieren.

Der Zähler wird pro Eintrag geführt, nicht pro anfragendem Host. Der Eintrag *.example.com ist ein einziger Zähler für alle Subdomains, andernfalls könnte die Beschränkung durch das Erfinden einer neuen Subdomain für jede Anfrage umgangen werden. Wenn nur ein Eintrag in der Liste ist, entspricht der Anteil dem Limit und es ändert sich nichts.

3. Öffentliche Endpunkte (ohne Schlüssel)

14 Referenz-Wörterbücher /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) werden öffentlich, ohne X-Api-Key bereitgestellt und kosten 0 Credits. Das Limit beträgt 30 Anfragen pro Stunde von einer IP-Adresse. Dieselben Daten sind als MCP Resources astroway://reference/<slug> für LLM-Agenten verfügbar.

Dasselbe Limit gilt für die restlichen öffentlichen Namespaces: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Kontingent für serverseitiges Rendering

30 Anfragen pro Stunde sind für den Browser gedacht: Jeder Besucher bringt seine eigene IP und sein eigenes Kontingent mit. Wenn jedoch dein Server (WordPress-Plugin, SSR, Cache-Aufwärmen) die Anfragen stellt, agiert eine einzige Adresse für alle Besucher und erschöpft das Limit nach wenigen Seitenneuladungen.

Sende in diesem Fall den Header X-AstroWay-Site-URL mit der Adresse der Website:

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

Modus	Limit
Ohne Header	30 Anfragen / Stunde pro IP; Widgets `/v1/embed/*` haben separate 120 / Stunde pro IP
Mit Header	300 Anfragen / Stunde pro Website, Obergrenze 600 / Stunde pro IP

Der Header ist in CORS erlaubt und stellt keine Anmeldeinformationen dar, daher bleibt die IP-Obergrenze bestehen: Egal wie viele Domains von einer Adresse genannt werden, insgesamt werden von dort nicht mehr als 600 Anfragen pro Stunde gesendet. Beide Zähler werden gleichzeitig benötigt: Der Website-Zähler greift, wenn eine Website von vielen Adressen (CDN, Load Balancer) angefragt wird, der IP-Zähler greift, wenn viele Namen von einer Adresse kommen.

Ein Aufruf ist nicht immer eine Einheit. Ein schwerer öffentlicher Endpunkt verbraucht mehr aus demselben Kontingent, anstatt ein separates zu erhalten. POST /v1/public/synastry kostet 3, da es sich um zwei Karten und eine Aspektmatrix mit 45 Zellen handelt: Die praktische Obergrenze dafür beträgt 10 pro Stunde von einer nicht deklarierten Adresse, 100 für eine deklarierte Website und 200 pro Adresse. Alles andere kostet 1. Wenn ein Aufruf mehr als eine Einheit kostet, wird dies in der Antwort im Header X-RateLimit-Cost angegeben, und ein Aufruf, der mehr kostet, als im Kontingent verbleibt, wird abgelehnt und geht nicht ins Minus.

Welcher Zähler gerade am engsten ist, verrät der Antwort-Header X-RateLimit-Scope (ip oder site). Die restlichen X-RateLimit-* Header beschreiben genau diesen, also nur einen der beiden Zähler. Der zweite ist in X-RateLimit-Counters sichtbar:

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

Das Format ist scope=verbleibend/limit durch Komma getrennt. Der Header erscheint nur, wenn es tatsächlich zwei Zähler gibt: ein anonymer Aufruf mit X-AstroWay-Site-URL. Ein Aufruf mit einem kostenpflichtigen Schlüssel wird nach deinem Schlüssel und deinem Tarif abgerechnet, dort gibt es nur einen Zähler und keinen Header. Lies ihn, wenn du von einem Server mehrere Domains von einer Adresse renderst: Das Website-Kontingent ist für jede Domain separat, aber die IP-Obergrenze ist gemeinsam, und diese wird zuerst erreicht.

Cache die Antworten auf deiner Seite: Das Tageshoroskop ändert sich im Laufe des Tages nicht, und ein Cache bis Mitternacht löst das Limitproblem vollständig.

Kostenpflichtiger Schlüssel für öffentliche Endpunkte. /v1/public/* und /v1/embed/* funktionieren ohne Schlüssel, aber wenn du ihn übermittelst (X-Api-Key), wird die Anfrage nach deinem Tarif und nicht nach dem anonymen Kontingent abgerechnet, und die Antwort enthält kein kostenloses Wasserzeichen. Dies ist sinnvoll für serverseitiges Rendering: Eine Maschine agiert für alle Besucher, und die anonymen 300/Stunde sind für sie zu wenig.

Kostentabelle

Eine vollständige, transparente Tabelle mit allen 771+ Endpunkten und ihren Kosten findest du auf der Seite Endpunktkosten. DivineAPI/AstrologyAPI/Prokerala veröffentlichen eine solche Tabelle nicht. Eine kurze Orientierungshilfe:

Tier	Credits	Typische Zeit	Beispiele
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	mehrere s	`/rectification/trutine`
6	500	bis zu 120 s	`/rectification`

Antwort-Header

Jede Antwort enthält:

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: wie viele Credits für diese Anfrage abgebucht wurden
X-Credits-Remaining: verbleibendes monatliches Budget
X-Credits-Limit: vollständiges monatliches Kreditbudget (gemäß Plan)
X-Credits-Reset: ISO-8601 Datum der Kontostandsaktualisierung
X-RateLimit-*: aktueller Status des Sliding Window (Standardformat)
- X-RateLimit-Scope: welcher Zähler gerade am engsten ist: ip, site oder key. Der Wert key bedeutet, dass die Anfrage über deinen Schlüssel und das Limit deines Tarifs abgerechnet wurde, nicht über das anonyme Kontingent.
- X-RateLimit-Counters: bei einem öffentlichen Endpunkt, der mit X-AstroWay-Site-URL aufgerufen wurde, alle Zähler, nach denen die Anfrage abgerechnet wurde, im Format scope=verbleibend/limit. Die oben genannten Header beschreiben nur den engsten.
- X-RateLimit-Reset: der Zeitpunkt, zu dem die älteste Anfrage aus dem Fenster fällt, d.h. wann ein Slot frei wird. Dies ist nicht die Zeit der vollständigen Öffnung des Buckets: Danach wird eine Anfrage durchgehen, und Reset verschiebt sich auf die nächste zeitlich. Ein Client, der bis Reset wartet und dann einen Stapel sendet, erhält erneut 429, daher ist es zuverlässiger, Anfragen einzeln zu senden oder Antworten auf deiner Seite zu cachen.
- Eine abgelehnte Anfrage (429) verbraucht kein Kontingent und verschiebt das Fenster nicht: Der Zähler wird nur durch erfolgreiche Anfragen aufgefüllt.
- X-RateLimit-Origin-Limit und X-RateLimit-Origin-Remaining: erscheinen nur, wenn die Anfrage über einen Eintrag aus der Liste der zulässigen Ursprünge erfolgte und zeigen den genau diesem Eintrag zugewiesenen Anteil an. Eine Ablehnung aufgrund dieses Anteils ist ebenfalls 429, und im Text wird angegeben, welcher Eintrag erschöpft ist.
X-Subscription-Status und X-Subscription-Grace-Ends: erscheinen nur, wenn der bezahlte Zeitraum bereits abgelaufen ist, aber die 3-tägige Kulanzperiode noch läuft (X-Subscription-Status: grace). Anfragen werden gemäß deinem Tarif bis zum Zeitpunkt in X-Subscription-Grace-Ends bedient, danach lautet die Antwort 402 SUBSCRIPTION_EXPIRED. Wenn dein Client die Header protokolliert, ist dies das früheste Signal, dass der Plan verlängert werden sollte.
X-Request-Id: Anfrage-ID, 32 hexadezimale Zeichen; nenne sie bei Kontaktaufnahme mit dem Support

Wie viel bereits ausgegeben wurde: drei Wege

Du kannst dein aktuelles Kreditguthaben auf drei Arten überprüfen – von der schnellsten bis zur detailliertesten:

In jeder Antwort: Die Header X-Credits-Remaining / X-Credits-Used / X-Credits-Limit werden bei jeder Anfrage (sogar bei einem Fehler) zurückgegeben. Du musst nichts zusätzlich aufrufen – der Kontostand ist immer sichtbar.
Mit einer separaten Anfrage: GET /v1/keys/usage mit deinem X-Api-Key gibt credits (used / remaining / limit / reset), usage (Anfragen für today / week / month) und die Top-20-Endpunkte der letzten 30 Tage zurück. Ein einziger Aufruf, ohne separaten Admin-Schlüssel.
Im Dashboard: api.astroway.info/dashboard/billing zeigt den Kontostand, die Nutzungsstatistik und die Aufschlüsselung nach Endpunkten in Echtzeit an.

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

Caching

Identische Anfragen innerhalb von 5 Minuten werden aus dem Cache zurückgegeben, ohne dass Credits abgebucht werden. Dies wird durch einen separaten Header angezeigt:

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

Was als “identisch” gilt:

Derselbe Endpunkt
Derselbe JSON-Body (Byte für Byte nach Normalisierung der Leerzeichen)
Derselbe API-Schlüssel

Dies ist sicher, da alle Endpunkte deterministisch sind – dieselbe Eingabe führt immer zu derselben Ausgabe.

Streaming und Webhooks

Streaming (`/stream/*`)

10 Stream-Endpunkte werden als Tier 1: 10 Credits pro Aufruf abgerechnet. Jeder Aufruf berechnet die Planetenpositionen neu, daher handelt es sich um eine vollständige Berechnung und nicht um einen gecachten Lookup – es gibt keinen separaten “günstigeren” Tarif pro Tick.

Jede Antwort enthält zwei Felder für eine sparsame Abfrage:

tickSeconds: empfohlenes Abfrageintervall;
nextEventAt: wann sich der Status das nächste Mal ändert.

Häufiger als tickSeconds abzufragen, verbrennt unnötig Credits: Der Status ändert sich nicht vor nextEventAt.

Webhooks (`/webhooks/*`)

CRUD-Operationen zur Abonnementverwaltung (/webhooks/subscribe, Liste, Ansicht, Löschen, /test) kosten jeweils Tier 1: 10 Credits. Dies sind seltene Aufrufe.

Die Zustellung eines Ereignisses (Server → deine URL) wird nicht berechnet: Credits werden nur für CRUD-Verwaltungsaufrufe abgebucht. Es werden 12 Ereignistypen unterstützt (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress usw.).

Webhooks sind ab dem Pro-Plan und höher verfügbar.

Was tun bei Überschreitung der Limits

`402 Payment Required`: Credits aufgebraucht

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

Optionen:

Plan-Upgrade: Du erhältst sofort ein neues Budget
Overage (Starter/Pro): wird automatisch aktiviert, wenn nicht in den Einstellungen deaktiviert
Auf Reset warten (Free): 1. des nächsten Monats

`429 Too Many Requests`: RPM überschritten

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

Der Header Retry-After: 12 ist ein Standard-HTTP-Header, dein HTTP-Client sollte ihn verstehen.

Korrekte Handhabung:

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

Budget im Voraus schätzen

Schätze vor der Integration ab, wie viele Credits du pro Monat benötigst:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Beispiel: Eine Anwendung mit 500 DAU, jeder Benutzer führt 3 Kartenberechnungen + 1 Synastrie pro Tag durch:

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

Der Budgetrechner befindet sich auf der Seite Tarife.

Weiter geht’s

Fehler: vollständiges Referenzhandbuch für Fehlercodes
Idempotenz: wie man wiederholte Anfragen sicher durchführt

Hilfreich?

Änderung vorschlagen

Zuletzt aktualisiert: 05.10.2026

// Vorherige Seite

Gematrie und die 72 Namen

Nächste Seite //

Kosten pro Endpoint