Errors and limits
One error shape for every endpoint. Errors are never charged.
Error shape
Every error is JSON with a readable error message (it names the field at fault), a stable code to branch on, and the request_id. These are real answers:
{
"code": "invalid_tz",
"error": "invalid \"tz\": use an IANA zone like Asia/Kolkata or an offset like +05:30",
"request_id": "req_gQcuMMyJSf"
}{
"code": "rate_limited",
"error": "rate limit: 2 calls a second on this plan. Retry after 1 s",
"request_id": "req_j75K8uNf6s"
}Branch on code, not on the message: messages can be reworded, codes don't change within v1. Every answer, error or not, also has the X-Request-Id and X-Units headers.
Status codes
- 200Code
(none)MeaningSuccess. Counts as the endpoint's API calls (1, or 5 to 30 for a heavy call). - 400Code
invalid_jsonMeaningThe body is not valid JSON. - 400Code
invalid_datetimeMeaningdatetime is missing or not like 1990-10-21T00:45. - 400Code
invalid_latinvalid_lonMeaningLatitude or longitude is missing or out of range. - 400Code
invalid_tzMeaningtz is not an IANA zone or an offset like +05:30. - 400Code
invalid_dateinvalid_timeinvalid_as_ofMeaningA date (YYYY-MM-DD) or time (HH:MM) is not valid. - 400Code
invalid_frominvalid_toinvalid_rangerange_too_longMeaningA muhurta date range is not valid, ends before it starts, or is too long. - 400Code
invalid_placeMeaningMarriage or childbirth muhurta without the event place: send lat, lon and tz, or a place object. - 400Code
invalid_boyinvalid_girlinvalid_motherinvalid_fatherMeaningA person object is missing. A bad field inside it uses that field's code, and the message names the person. - 400Code
invalid_purposeMeaningpurpose is missing or not one of GET /muhurta/purposes. - 400Code
invalid_chartinvalid_kindinvalid_styleinvalid_formatinvalid_sectionsinvalid_spreadMeaningA value is not in the list the endpoint accepts. - 400Code
invalid_sinceMeaningsince on GET /logs is not an ISO time. - 400Code
invalid_monthMeaningmonth on GET /usage is not like 2026-11. - 400Code
invalid_end_userMeaningX-End-User is longer than 64 characters or has characters other than letters, numbers, _ and -. - 400Code
unsupported_langMeaninglang is not one of the 12 codes. - 400Code
unsupported_ayanamsaMeaningayanamsa is not lahiri. Lahiri is the only one today and the default. - 400Code
invalid_qinvalid_countryinvalid_limitMeaningPlace search: q is not 3 to 100 characters, country is not a 2-letter code, or limit is not 1 to 10. - 400Code
missing_questionMeaningAI chat: question is empty. - 400Code
question_too_longMeaningAI chat: question is longer than 2,000 characters. - 400Code
invalid_historyMeaningAI chat: history is not a list of {role: user or assistant, content}. - 400Code
invalid_voiceMeaningAI voice calls: voice is not one of the listed voices. - 400Code
invalid_max_minutesMeaningAI voice calls: max_minutes is not a whole number from 1 to 15. - 400Code
greeting_too_longMeaningAI voice calls: greeting is longer than 300 characters. - 401Code
missing_keyMeaningNo Authorization header. - 401Code
unknown_keyMeaningThe key is wrong, revoked, or past its 24-hour rotation window. - 403Code
not_allowedMeaningThe key has an allow list and the call came from another IP or domain. - 403Code
ai_calls_not_on_planMeaningAI voice calls: they start on the Starter plan. - 404Code
no_such_endpointMeaningWrong path or method. - 404Code
no_such_callMeaningAI voice calls: no call with that id on your account. - 429Code
rate_limitedMeaningMore calls a second than your plan allows. Retry-After: 1. - 429Code
monthly_limitMeaningFree plan: the month's API calls are used up. Retry-After counts to the 1st of next month, India time. Upgrade to keep calling. - 429Code
spend_capMeaningPaid plan: the next call would pass your monthly spend cap. Raise it in Billing, or wait for the next month. - 429Code
ai_limitMeaningAI: no questions or call minutes left. Buy a pack in Billing (on Free, upgrade first). API calls keep working. - 429Code
too_many_callsMeaningAI voice calls: your plan's calls at once are all running. End one first. - 500Code
internalMeaningGET /logs and GET /usage only: the log store could not be read. Retry. - 502Code
engine_unavailableMeaningOur calculation engine did not answer. Retry with backoff. - 502Code
engine_errorMeaningThe calculation failed. Retry once; if it repeats, send us the request_id. - 502Code
places_failedMeaningPlace search could not answer. Retry with backoff. - 502Code
ai_failedMeaningAI chat or voice: the answer or the call could not be produced. The question or minutes go back to your pack. Retry. - 503Code
ai_unavailableMeaningAI chat or voice is switched off on the server. - 503Code
busyMeaningLong muhurta searches are busy. Retry after 30 seconds (Retry-After). Nothing is counted. - 503Code
places_unavailableMeaningPlace search is not available just now. Retry later, or send lat, lon and tz yourself.
units 0.Limits per plan
Every plan has every endpoint. Plans differ only in volume and speed.
- FreeAPI calls a month1,000Calls a second2After the monthly API callsBlocked until next month (429 monthly_limit)
- StarterAPI calls a month1,00,000Calls a second10After the monthly API callsExtra calls, billed per 1,000, up to your spend cap
- GrowthAPI calls a month5,00,000Calls a second50After the monthly API callsExtra calls, billed per 1,000, up to your spend cap
- ScaleAPI calls a month25,00,000Calls a second200After the monthly API callsExtra calls, billed per 1,000, up to your spend cap
Most requests count as 1 API call. Heavy calls count for more: full kundli (5), yogas (5), chart PDF (5), muhurta search (5, or 10 over 90 days), marriage muhurta (5, 15 over 90 days, 25 over 180), childbirth muhurta (30). GET /muhurta/purposes and GET /logs are free. See prices
Monthly spend cap
On a paid plan, API calls beyond the plan are billed at the extra-call price. Set a monthly cap for that extra in Billing. When the next call would pass it, calls get 429 spend_cap until you raise the cap or the month ends. Without a cap, calls never stop.
429 and Retry-After
Every 429 has a Retry-After header in seconds. For rate_limited it is 1: wait, then retry, with some jitter if many workers retry at once. For monthly_limit and spend_cap it counts to the next month, so don't retry in a loop: check the code first.
async function call(url, init, tries = 3) {
const res = await fetch(url, init);
if (res.status === 429 && tries > 0) {
const { code } = await res.clone().json();
if (code !== "rate_limited") return res; // monthly_limit or spend_cap: retrying won't help
const wait = Number(res.headers.get("Retry-After") ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250));
return call(url, init, tries - 1);
}
return res;
}Timeouts
Most calls answer in well under a second. Childbirth muhurta takes one to two minutes and marriage muhurta up to a minute for a full year, so set your client timeout to 60 seconds for those. A call that times out on your side may still finish and count; check Request logs before retrying a heavy call.