vedicAPI

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:

400 Bad Request
{
  "code": "invalid_tz",
  "error": "invalid \"tz\": use an IANA zone like Asia/Kolkata or an offset like +05:30",
  "request_id": "req_gQcuMMyJSf"
}
429 Too Many Requests · Retry-After: 1
{
  "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

  • 200
    Code(none)
    MeaningSuccess. Counts as the endpoint's API calls (1, or 5 to 30 for a heavy call).
  • 400
    Codeinvalid_json
    MeaningThe body is not valid JSON.
  • 400
    Codeinvalid_datetime
    Meaningdatetime is missing or not like 1990-10-21T00:45.
  • 400
    Codeinvalid_latinvalid_lon
    MeaningLatitude or longitude is missing or out of range.
  • 400
    Codeinvalid_tz
    Meaningtz is not an IANA zone or an offset like +05:30.
  • 400
    Codeinvalid_dateinvalid_timeinvalid_as_of
    MeaningA date (YYYY-MM-DD) or time (HH:MM) is not valid.
  • 400
    Codeinvalid_frominvalid_toinvalid_rangerange_too_long
    MeaningA muhurta date range is not valid, ends before it starts, or is too long.
  • 400
    Codeinvalid_place
    MeaningMarriage or childbirth muhurta without the event place: send lat, lon and tz, or a place object.
  • 400
    Codeinvalid_boyinvalid_girlinvalid_motherinvalid_father
    MeaningA person object is missing. A bad field inside it uses that field's code, and the message names the person.
  • 400
    Codeinvalid_purpose
    Meaningpurpose is missing or not one of GET /muhurta/purposes.
  • 400
    Codeinvalid_chartinvalid_kindinvalid_styleinvalid_formatinvalid_sectionsinvalid_spread
    MeaningA value is not in the list the endpoint accepts.
  • 400
    Codeinvalid_since
    Meaningsince on GET /logs is not an ISO time.
  • 400
    Codeinvalid_month
    Meaningmonth on GET /usage is not like 2026-11.
  • 400
    Codeinvalid_end_user
    MeaningX-End-User is longer than 64 characters or has characters other than letters, numbers, _ and -.
  • 400
    Codeunsupported_lang
    Meaninglang is not one of the 12 codes.
  • 400
    Codeunsupported_ayanamsa
    Meaningayanamsa is not lahiri. Lahiri is the only one today and the default.
  • 400
    Codeinvalid_qinvalid_countryinvalid_limit
    MeaningPlace search: q is not 3 to 100 characters, country is not a 2-letter code, or limit is not 1 to 10.
  • 400
    Codemissing_question
    MeaningAI chat: question is empty.
  • 400
    Codequestion_too_long
    MeaningAI chat: question is longer than 2,000 characters.
  • 400
    Codeinvalid_history
    MeaningAI chat: history is not a list of {role: user or assistant, content}.
  • 400
    Codeinvalid_voice
    MeaningAI voice calls: voice is not one of the listed voices.
  • 400
    Codeinvalid_max_minutes
    MeaningAI voice calls: max_minutes is not a whole number from 1 to 15.
  • 400
    Codegreeting_too_long
    MeaningAI voice calls: greeting is longer than 300 characters.
  • 401
    Codemissing_key
    MeaningNo Authorization header.
  • 401
    Codeunknown_key
    MeaningThe key is wrong, revoked, or past its 24-hour rotation window.
  • 403
    Codenot_allowed
    MeaningThe key has an allow list and the call came from another IP or domain.
  • 403
    Codeai_calls_not_on_plan
    MeaningAI voice calls: they start on the Starter plan.
  • 404
    Codeno_such_endpoint
    MeaningWrong path or method.
  • 404
    Codeno_such_call
    MeaningAI voice calls: no call with that id on your account.
  • 429
    Coderate_limited
    MeaningMore calls a second than your plan allows. Retry-After: 1.
  • 429
    Codemonthly_limit
    MeaningFree plan: the month's API calls are used up. Retry-After counts to the 1st of next month, India time. Upgrade to keep calling.
  • 429
    Codespend_cap
    MeaningPaid plan: the next call would pass your monthly spend cap. Raise it in Billing, or wait for the next month.
  • 429
    Codeai_limit
    MeaningAI: no questions or call minutes left. Buy a pack in Billing (on Free, upgrade first). API calls keep working.
  • 429
    Codetoo_many_calls
    MeaningAI voice calls: your plan's calls at once are all running. End one first.
  • 500
    Codeinternal
    MeaningGET /logs and GET /usage only: the log store could not be read. Retry.
  • 502
    Codeengine_unavailable
    MeaningOur calculation engine did not answer. Retry with backoff.
  • 502
    Codeengine_error
    MeaningThe calculation failed. Retry once; if it repeats, send us the request_id.
  • 502
    Codeplaces_failed
    MeaningPlace search could not answer. Retry with backoff.
  • 502
    Codeai_failed
    MeaningAI chat or voice: the answer or the call could not be produced. The question or minutes go back to your pack. Retry.
  • 503
    Codeai_unavailable
    MeaningAI chat or voice is switched off on the server.
  • 503
    Codebusy
    MeaningLong muhurta searches are busy. Retry after 30 seconds (Retry-After). Nothing is counted.
  • 503
    Codeplaces_unavailable
    MeaningPlace search is not available just now. Retry later, or send lat, lon and tz yourself.
Errors (4xx and 5xx) are never counted toward your monthly API calls. They still show in Request logs, with units 0.

Limits per plan

Every plan has every endpoint. Plans differ only in volume and speed.

  • Free
    API calls a month1,000
    Calls a second2
    After the monthly API callsBlocked until next month (429 monthly_limit)
  • Starter
    API calls a month1,00,000
    Calls a second10
    After the monthly API callsExtra calls, billed per 1,000, up to your spend cap
  • Growth
    API calls a month5,00,000
    Calls a second50
    After the monthly API callsExtra calls, billed per 1,000, up to your spend cap
  • Scale
    API calls a month25,00,000
    Calls a second200
    After 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.

JavaScript
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.