astroAPI

Auth & Limits

Authentifizierung, Caching, Rate-Limit, Fehler

Was Konsumenten ueber den Betrieb von astroAPI wissen sollten — kompakt auf einer Seite.

Authentifizierung

Jeder Aufruf braucht den Header X-API-Key: ak_(test|live)_<32hex>. Test-Keys laufen gegen das produktive System, sind aber als solche markiert (Plan free, kleinere Limits) und im Usage-Log nachvollziehbar.

Niemals einen Key in Browser-JavaScript einbetten — der Key liegt dort offen. Fuer Browser-Anwendungen: Server-Side-Proxy mit Key auf dem Server, Frontend ruft den Proxy an. Der Playground macht es genauso.

Pruefe deinen Key mit:

curl -sS -H "X-API-Key: ak_test_..." https://astroapi.services/v1/me

Rate-Limit

Pro Plan und Stunde:

  • free: 60 Requests/h
  • basic: 1.000 Requests/h
  • pro: 10.000 Requests/h
  • internal: keine Drosselung

Bei jedem Response setzt die API folgende Header:

  • X-RateLimit-Limit: Stundenlimit deines Plans.
  • X-RateLimit-Remaining: Verbleibend in dieser Stunde.
  • X-RateLimit-Source: redis oder db (technisches Backend, nuetzlich beim Debugging).

Bei Ueberschreitung: HTTP 429 mit Body {"error":{"code":"rate_limit_exceeded","message":"..."}} und Header Retry-After: 3600.

HTTP-Caching

Alle deterministischen Berechnungs-Endpunkte (Planeten, Aspekte, Radix, Wuerden, Aufgaenge ...) liefern:

  • Cache-Control: public, max-age=31536000, immutable
  • ETag: "<sha1>"

Sende den ETag beim naechsten gleichen Request mit If-None-Match — bei Treffer bekommst du HTTP 304 ohne Body und ohne dass dein Stundenlimit dadurch gross belastet wird.

Endpunkte mit optionalem target_datetime-Default (profections, firdaria, zodiacal-releasing) sind nur cachebar, wenn du target_datetime explizit setzt — sonst ist die Antwort von der Serverzeit abhaengig und nicht reproduzierbar.

Fehlerformat

Bei jedem Fehler antwortet die API in einheitlichem Format:

{
  "error": {
    "code": "invalid_input",
    "message": "Parameter \"datetime\" is required.",
    "request_id": "9f8a4c12-..."
  }
}

request_id ist ein UUID, das bei Support-Anfragen den Vorgang im Server-Log lokalisierbar macht. Es wird zusaetzlich im Header X-Request-Id ausgeliefert.

Standard-Codes:

  • 400 invalid_input — Body/Query stimmt nicht.
  • 401 unauthorized — Key fehlt oder ist ungueltig.
  • 404 not_found — Pfad existiert nicht.
  • 429 rate_limit_exceeded — Stundenlimit ueberschritten.
  • 500 ephemeris_error / internal_error — uns ist was kaputtgegangen, request_id mailen.

CORS

Browser-Clients von https://astroapi.services aus funktionieren ohne Konfiguration. Externe Origins muessen vom Admin auf die Whitelist gesetzt werden (Env ALLOWED_ORIGINS) — ohne Whitelist faellt CORS auf Wildcard zurueck (nicht produktiv).

Exponiert werden alle Antwort-Header, die fuer den Client relevant sind: X-Request-Id, alle X-RateLimit-*, Retry-After, ETag.