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 `x-api-key` or `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.
`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

Send an Idempotency-Key header on writes you might retry. A repeated request with the same key reuses the original charge instead of billing twice — safe to retry after a timeout or a dropped connection.

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