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`	—	Missing, invalid or inactive API key	Check the key and the `x-api-key` or `Authorization: Bearer` header.
`402`	`PAYMENT_REQUIRED`	Insufficient wallet balance	Top up (Enterprise) or check plan credits — see Pricing.
`403`	`PLAN_UPGRADE_REQUIRED`	Feature not on your plan (e.g. Vedika Swift / `speed:"fast"` needs Business+)	Upgrade the plan or use an available tier.
`429`	—	Rate limit exceeded for your plan tier	Back off and retry — see Rate Limits.
`503`	`ECO_UNAVAILABLE`	The requested engine is temporarily unavailable (e.g. `speed:"eco"`)	Retry with backoff, or fall back to another tier.
`503`	—	Billing 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": { "...": "..." } }'