Skip to content
Occult API

Domain Gotchas

How the API actually behaves in the places where generated code usually goes wrong. Each item below is how the server handles the request, not a style preference.

Requests

  • The trailing slash is required. /api/astro/tithi/ works; /api/astro/tithi answers 301, and a client that follows the redirect re-sends it as a GET without the body.
  • The same value has different field names on different endpoints. The moment is date_time almost everywhere but datetime on /api/astro/chart/ and the divisional charts; the offset is usually timezone_as_float but timezone, tz or time_zone on some; the lunar node is rahu, node or node_type, with different defaults. Build each body from that endpoint's field list rather than reusing one body everywhere.
  • Longitude is negative west of Greenwich and latitude negative south of the equator. New York is -74.006, not 74.006.
  • Latitude limits differ: most chart and panchang endpoints accept up to ±89.9, the Ashtamangala and Jamakkol Prashna endpoints up to ±66. A value outside the endpoint's range is rejected with 400.

Wrong input that still returns 200

  • A date_time without an offset is not read as the place's local time: most endpoints take it as UTC+05:30, a few as UTC. The response is a normal 200 for a different moment — sometimes the previous day. Always send an offset or Z.
  • timezone_as_float is not checked against the offset in date_time. If they disagree you get a 200 for the wrong moment. Use the offset in force on that date (summer time included), not today's; /api/astro/date_time/ resolves it from the coordinates.
  • A few fields fall back instead of failing: on /api/astro/chart/ any ascendant_pos other than start or end means the house cusp, and on /api/astro/festival/ any moon_option other than poornima behaves as amavas. A typo there changes the answer without an error.

Keys

  • On an endpoint with a key table, a key that is not in it rejects the whole request with 400, and the message names the unrecognised keys. Nothing is calculated and nothing is charged.
  • Key names are exact and sometimes surprising: /api/astro/panchanga/ uses yogam for the day's yoga, rahu_kaalam and calcualte_special_tithi (spelled that way). Copy them from the key table instead of guessing.
  • A key that needs an extra field fails with 400 when the field is missing, for example the phone_number key on /api/astro/numerology/ without a phone_number value.
  • One successful call costs one credit however many keys it asks for. Ask for everything you need in one call — tithi, vaara, yogam and karana together — rather than one call per key.
  • Single-purpose endpoints such as /api/astro/tithi/ and /api/astro/rahu-kaal/ have no key table: they always return the same fixed set, and a keys array sent to them is not used.
  • On /api/astro/numerology/ the valid keys depend on system. A key from another system's set returns 400 naming it.

Credits, errors and limits

  • Most endpoints cost one credit per successful call. /api/astro/chat/, /api/astro/pdf/horoscope/ and /api/astro/pdf/yearbook/ cost 25 each — keep them out of loops and retries.
  • Failed calls are free: credits are reserved before the calculation and returned on any non-2xx response, which then carries X-Credits-Charged: 0.
  • Metered responses carry X-Credits-Cost, X-Credits-Charged and X-Credits-Remaining, plus the per-minute X-RateLimit-Limit and X-RateLimit-Remaining. Read them rather than tracking the balance yourself.
  • Out of credits returns 402 with message insufficient_credits; its data gives cost_credits, credits_remaining and recharge_url. Retrying will not help until the plan is upgraded or its quota resets.
  • Over the per-minute limit returns 429 with message api_key_rate_limited and a Retry-After header (also retry_after_seconds in data). Wait that long before retrying.
  • A malformed, revoked or expired key returns 401 invalid_api_key. A route, scope or IP address your key may not use returns 403 endpoint_not_allowed, scope_not_allowed or ip_not_allowed.
  • Errors from the key and credit checks look like { "error": "…", "message": "insufficient_credits", "is_error": true, "data": { … } }: branch on the code in message. Calculation responses use the envelope { "data": {}, "status": 400, "is_error": true, "message": "…" } on failure, with the reason as text in message. Both carry is_error.
  • The two PDF endpoints return the PDF itself (application/pdf), not JSON. Write the body to a file; there is no download link to fetch afterwards.

Astrology

  • The Vedic endpoints are sidereal and do the ayanamsa correction on the server; the /api/astro/western/ routes are tropical by default. Do not subtract an ayanamsa from the output yourself.
  • /api/astro/kp-chart/ uses Placidus cusps on the sidereal zodiac, so its house placements can differ from /api/astro/chart/ for the same birth. That is the KP method, not an inconsistency.
  • Rashifal is a sign-based forecast with no birth chart: send rashi as an English sign name such as leo, not birth data.
  • Tarot draws are random unless you send seed. Every response returns the seed it used, so store it if a reading must be shown again exactly.
  • /api/astro/numerology/iching/ maps a date and a name onto the 64 hexagrams numerically. Nothing is cast, so there are no changing lines and no second hexagram.

Next

Field FormatsThe exact request formatsCoverage and ScopeWhat the API covers and where it stops