Errors & limits
Errors use standard HTTP status codes and a stable, machine-readable code.
Error format
{
"error": {
"code": "insufficient_credits",
"message": "Not enough balance in your API wallet. Recharge at /developers."
}
}Branch on error.code; error.message is for people and may change.
Error codes
| Status | Code | Meaning | Charged |
|---|---|---|---|
| 400 | invalid_request | The body is missing a field or a value is invalid. | No |
| 400 | chart_failed | The Kundli could not be computed. Check date, time, place and timezone. | No |
| 401 | invalid_api_key | Missing, wrong or revoked API key. | No |
| 402 | insufficient_credits | Your wallet balance is too low. Recharge at /developers. | No |
| 404 | not_found | The consultation does not exist or belongs to another account. | No |
| 409 | consultation_closed | The consultation closed 7 days after it started. Create a new one. | No |
| 409 | consultation_not_ready | The consultation is not ready to take questions yet. Retry shortly. | No |
| 429 | answer_pending | Two questions are already waiting for answers. Wait for one to be answered. | No |
| 503 | unavailable | Kaal is temporarily unavailable. Retry later. | No |
Limits
| Limit | Value |
|---|---|
| Consultation lifetime | 7 days from creation, then read-only |
| Question length | 2–600 characters |
| Unanswered questions per consultation | 2 |
fullName length | 120 characters |
| Active API keys per account | 10 |
Retrying
503 unavailable: retry with backoff (for example after 30 s, then 60 s).429 answer_pending: poll the consultation and ask again oncestatusisready.409 consultation_closed: start a new consultation; closed ones cannot be resumed.