Fachliche Fallstricke

So verhält sich die API genau dort, wo generierter Code meistens danebenliegt. Jeder Punkt beschreibt, wie der Server die Anfrage tatsächlich behandelt – es geht nicht um Stilfragen.

Anfragen

Der Schrägstrich am Ende ist Pflicht. /api/astro/tithi/ funktioniert; /api/astro/tithi liefert 301, und ein Client, der der Umleitung folgt, schickt die Anfrage erneut als GET ohne Body.
Derselbe Wert heißt bei verschiedenen Endpoints unterschiedlich. Der Zeitpunkt ist fast überall date_time, aber datetime bei /api/astro/chart/ und den Teilhoroskopen. Der Offset heißt meist timezone_as_float, bei manchen aber timezone, tz oder time_zone. Der Mondknoten heißt rahu, node oder node_type – mit unterschiedlichen Standardwerten. Bau jeden Body aus der Feldliste des jeweiligen Endpoints, statt einen Body überall wiederzuverwenden.
Westlich von Greenwich ist die Länge negativ, südlich des Äquators die Breite. New York liegt bei -74.006, nicht bei 74.006.
Die Grenzen für die Breite sind unterschiedlich: Die meisten Horoskop- und Panchang-Endpoints akzeptieren bis ±89.9, die Prashna-Endpoints Ashtamangala und Jamakkol nur bis ±66. Ein Wert außerhalb des Bereichs wird mit 400 abgelehnt.

Falsche Eingaben, die trotzdem 200 liefern

Ein date_time ohne Offset wird nicht als Ortszeit gelesen: Die meisten Endpoints nehmen UTC+05:30 an, einige UTC. Du bekommst ein ganz normales 200 – nur für einen anderen Zeitpunkt, manchmal sogar den Vortag. Schick also immer einen Offset oder Z mit.
timezone_as_float wird nicht mit dem Offset in date_time abgeglichen. Passen beide nicht zusammen, bekommst du ein 200 für den falschen Zeitpunkt. Nimm den Offset, der an diesem Datum galt (inklusive Sommerzeit), nicht den heutigen. /api/astro/date_time/ ermittelt ihn aus den Koordinaten.
Einige Felder greifen auf einen Standard zurück, statt einen Fehler zu liefern: Bei /api/astro/chart/ bedeutet jedes ascendant_pos außer start oder end die Häuserspitze, und bei /api/astro/festival/ verhält sich jedes moon_option außer poornima wie amavas. Ein Tippfehler ändert dort das Ergebnis, ohne dass eine Fehlermeldung kommt.

Keys

Bei einem Endpoint mit Key-Tabelle lässt ein Key, der nicht darin steht, die ganze Anfrage mit 400 scheitern; die Meldung nennt die unbekannten Keys. Es wird nichts berechnet und nichts abgerechnet.
Key-Namen müssen exakt stimmen und sind manchmal überraschend: /api/astro/panchanga/ nutzt yogam für das Yoga des Tages, rahu_kaalam und calcualte_special_tithi (genau so geschrieben). Kopier sie aus der Key-Tabelle, statt zu raten.
Ein Key, der ein zusätzliches Feld braucht, scheitert mit 400, wenn das Feld fehlt – zum Beispiel der Key phone_number bei /api/astro/numerology/ ohne Wert für phone_number.
Ein erfolgreicher Aufruf kostet einen Credit, egal wie viele Keys er abfragt. Frag alles Nötige in einem Aufruf ab – tithi, vaara, yogam und karana zusammen –, statt für jeden Key einen eigenen Aufruf zu senden.
Endpoints mit nur einer Aufgabe wie /api/astro/tithi/ und /api/astro/rahu-kaal/ haben keine Key-Tabelle: Sie liefern immer dieselben festen Werte, und ein mitgeschicktes keys-Array wird ignoriert.
Bei /api/astro/numerology/ hängen die gültigen Keys von system ab. Ein Key aus einem anderen System liefert 400, und die Meldung nennt ihn.

Credits, Fehler und Limits

Die meisten Endpoints kosten einen Credit pro erfolgreichem Aufruf. /api/astro/chat/, /api/astro/pdf/horoscope/ und /api/astro/pdf/yearbook/ kosten je 25 – lass sie aus Schleifen und automatischen Wiederholungen heraus.
Fehlgeschlagene Aufrufe sind kostenlos: Credits werden vor der Berechnung reserviert und bei jeder Antwort außerhalb von 2xx zurückgebucht. Die Antwort enthält dann X-Credits-Charged: 0.
Abgerechnete Antworten enthalten X-Credits-Cost, X-Credits-Charged und X-Credits-Remaining, dazu die Minutenwerte X-RateLimit-Limit und X-RateLimit-Remaining. Lies sie aus, statt das Guthaben selbst mitzurechnen.
Sind keine Credits mehr da, kommt 402 mit message insufficient_credits; data enthält cost_credits, credits_remaining und recharge_url. Erneute Versuche helfen erst, wenn der Tarif hochgestuft oder sein Kontingent zurückgesetzt ist.
Wer das Minutenlimit überschreitet, bekommt 429 mit message api_key_rate_limited und dem Header Retry-After (zusätzlich retry_after_seconds in data). Warte so lange, bevor du es erneut versuchst.
Ein fehlerhafter, widerrufener oder abgelaufener Schlüssel liefert 401 invalid_api_key. Eine Route, ein Scope oder eine IP-Adresse, die dein Schlüssel nicht nutzen darf, liefert 403 endpoint_not_allowed, scope_not_allowed oder ip_not_allowed.
Fehler aus der Schlüssel- und Credit-Prüfung sehen so aus: { "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } } – verzweige anhand des Codes in message. Berechnungen antworten im Fehlerfall im Format { "data": {}, "status": 400, "is_error": true, "message": "…" }, mit dem Grund als Text in message. Beide enthalten is_error.
Die beiden PDF-Endpoints liefern direkt das PDF (application/pdf), kein JSON. Schreib den Body in eine Datei – einen Download-Link, den du danach abrufen müsstest, gibt es nicht.

Astrologie

Die vedischen Endpoints rechnen siderisch und wenden die Ayanamsa-Korrektur schon auf dem Server an; die Routen unter /api/astro/western/ sind standardmäßig tropisch. Zieh also nicht selbst noch ein Ayanamsa von der Ausgabe ab.
/api/astro/kp-chart/ nutzt Placidus-Häuserspitzen im siderischen Tierkreis. Deshalb können die Hausstellungen für dieselbe Geburt von /api/astro/chart/ abweichen. Das ist die KP-Methode, kein Widerspruch.
Rashifal ist eine Vorhersage pro Tierkreiszeichen, ganz ohne Geburtshoroskop: Schick rashi als englischen Zeichennamen wie leo, keine Geburtsdaten.
Tarot-Ziehungen sind zufällig, solange du kein seed mitschickst. Jede Antwort gibt den verwendeten Seed zurück – speicher ihn, wenn eine Legung später exakt gleich angezeigt werden soll.
/api/astro/numerology/iching/ ordnet ein Datum und einen Namen rechnerisch einem der 64 Hexagramme zu. Es wird nichts geworfen, daher gibt es keine wandelnden Linien und kein zweites Hexagramm.

Weiter

FeldformateDie exakten Anfrageformate Abdeckung und UmfangWas die API abdeckt und wo sie aufhört