Error Codes

What each error code means, whether you were charged, and how to fix it.

Every error response is JSON with a non-2xx HTTP status. Where the API distinguishes a specific cause it also returns a machine-readable code field — check that first, then fall back to the HTTP status.

#Common error codes

HTTP	Code	Meaning	Fix
`400`	`INVALID_INPUT`	Blank `question` or malformed `birthDetails`	Send a non-empty `question` and a valid chart (all four `birthDetails` fields).
`401`	`UNAUTHORIZED`	No API key was sent	Send the key as `Authorization: Bearer`.
`401`	`INVALID_FORMAT`	The key is not in the expected format	Use the full key from your dashboard, not a documentation placeholder.
`401`	`INVALID_API_KEY`	The key is unknown or inactive	Check the key in your dashboard and the header you send it in.
`401`	`KEY_EXPIRED`	The API key has expired	Generate a new key from your dashboard.
`402`	`INSUFFICIENT_BALANCE`	Wallet balance is too low for this call	Add funds to your wallet — see Pricing.
`403`	`TEST_KEY_REJECTED`	A `vk_test_` key was used on production	Use a `vk_live_` key for production, or use the sandbox with a sandbox key.
`403`	`SUBSCRIPTION_INACTIVE`	The account or subscription is not active	Check your account status in the dashboard or contact support.
`403`	`SWIFT_PLAN_REQUIRED`	`speed:"fast"` (Vedika Swift) was requested on a Starter or Professional plan. Nothing is charged.	Vedika Swift is included on Business, Enterprise and Flagship. Upgrade at Pricing, or omit `speed` to use Vedika Standard.
`403`	`LANGUAGE_PLAN_REQUIRED`	A Starter key asked for a `language` outside English and the ten included Indian languages (Hindi, Bengali, Telugu, Tamil, Gujarati, Kannada, Malayalam, Marathi, Punjabi, Odia). Nothing is charged.	All 30 languages are included from Professional. Upgrade at Pricing, or send one of the included language codes. Starter keys are held to this from 20 Nov 2026.
`422`	`IDEMPOTENCY_NOT_SUPPORTED`	A retry key was sent to an endpoint that does not accept one. Nothing is charged.	Send the request again without `Idempotency-Key`, `X-Idempotency-Key` or your own `X-Request-Id`. See Retries & idempotency.
`429`	`RATE_LIMIT_EXCEEDED`	Per-minute rate limit exceeded for your plan tier	Back off and retry after the `Retry-After` header — see Rate Limits.
`429`	`DAILY_LIMIT_EXCEEDED`	Daily call limit for your plan reached	Retry after the `Retry-After` delay, or move to a higher plan.
`429`	`IP_BLOCKED`	Too many failed authentication attempts from this IP address	Fix the key being sent, then retry after the `Retry-After` delay.
`503`	`ECO_UNAVAILABLE`	The requested engine is temporarily unavailable (e.g. `speed:"eco"`)	Retry with backoff, or fall back to another tier.
`503`	`SERVICE_UNAVAILABLE`	Billing or a dependency is temporarily unavailable	Retry with exponential backoff.

#Billing on error

Note

Billing is fail-closed: no answer is ever returned unless the charge is reserved and settled. A 400 on bad input is rejected before any wallet reservation runs, so malformed requests are never charged.

#Retries & idempotency

Every successful call is charged, including a repeat request for a chart you already fetched. Store results you will show again on your side.

To retry after a timeout or a dropped connection without paying twice, send an Idempotency-Key header to an endpoint that accepts one: the AI query and batch endpoints, the tithi, nakshatra, yoga and karana endpoints, the dasha endpoints, ashtakoota matching and the Vastu calculation routes. A retry with the same key and body within 24 hours reuses the original charge. The full list is in the API reference.

Most other chart endpoints, including birth chart, kundli, panchang, horoscope and the matrimony routes, refuse a retry key with 422 IDEMPOTENCY_NOT_SUPPORTED. Nothing is charged; send the request again without Idempotency-Key, X-Idempotency-Key or your own X-Request-Id.

curl -s https://api.vedika.io/api/v1/astrology/query \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-b710-4a15-9c1e-0f6d2a5c9b31" \
  -d '{ "question": "...", "birthDetails": { "...": "..." } }'