Domain Gotchas

LLMs hallucinate confidently in these areas. The specific traps:

Astrology

• Retrograde is per-planet, not "global". Natal chart planets include isRetrograde: boolean per planet. Never generate "Mercury retrograde globally" UI copy — check the specific planet in the response.
• Timezone affects Western calculations more than Vedic. Western natal charts must respect DST at time of birth. Use the timezone from the Location API, not the user's current clock.
• Sign in horoscope path is lowercase. /astrology/horoscope/aries/daily, never /Aries/daily or zodiac symbols.

Vedic

• Ayanamsa is server-side in Vedic. LLMs default to tropical / Western math. Vedic endpoints apply sidereal Lahiri ayanamsa server-side. KP endpoints accept kp-newcomb (default), kp-old, lahiri, or custom. Do not try to "correct" server output by subtracting ayanamsa in client code.
• Tithi count is 30 (15 Shukla + 15 Krishna), not 2. Older LLM training data conflates Purnima and Amavasya as single tithis. Our split is authoritative — there are 30 distinct tithis in a lunar month.
• Rahu and Ketu are shadow points, not planets. They do not appear in a real ephemeris. Endpoints accept nodeType of true-node or mean-node to select which calculation to use.
• Nakshatra count is 27. Abhijit is sometimes treated as a 28th in some schools, but this API uses the standard 27.
• KP planet lists use retrograde, not isRetrograde. Stay consistent with the field on the chart endpoint you actually called.

Numerology

• Numerology dates use three integers, not a date string. { year: 1990, month: 1, day: 15 }. A birthDate string fails validation.
• fullName means birth-certificate name. Nicknames or married names produce different numbers — every letter contributes.

Tarot

• Tarot reversals are a product choice. allowReversals: false means no reversed cards in that draw, period. It is not cosmically meaningful — it is a config flag.
• Card IDs are kebab-case slugs. the-fool, ace-of-cups, three-of-swords. Not numeric like major-01 or cups-03.

Biorhythm

• Seed-based daily endpoints are DETERMINISTIC per (seed, date) pair. Same seed + same date = same reading. This is by design for push-notification consistency. Do not describe it as "cached" or retry on stale responses.

I-Ching

• Hexagram detail uses an integer path param 1-64. Not the Chinese name (qian) or pinyin. GET /iching/hexagrams/1.
• Daily and cast are different verbs. Daily is POST, random cast is GET, seeded daily cast is POST. Do not unify them.

Angel Numbers

• Angel number lookup works for any positive integer. Digit-root fallback covers non-canonical numbers. Do not generate validation logic that rejects non-111/222/333 patterns.