Errors & limits
Every error response is JSON with two fields: a stable machine-readable error
code and a human-readable message. Branch on the code.
{
"error": "permission_denied",
"message": "This key needs the write permission."
}
Status codes
| Status | Code | Meaning | Retry? |
|---|---|---|---|
400 |
invalid_request |
A required field is missing or out of range. | No |
401 |
invalid_key |
No key was presented, or the key is unknown/revoked. | No |
401 |
invalid_device_key |
The device key is unknown or revoked. | No |
403 |
permission_denied |
The key is valid but lacks the required permission. | No |
404 |
not_found |
The resource or endpoint does not exist. | No |
429 |
rate_limited |
Daily allowance or endpoint burst limit reached. | Yes, with backoff |
500 |
server_error |
Unexpected failure — retry with backoff. | Yes, with backoff |
Rate limits
| Scope | Limit | Window |
|---|---|---|
| API key — daily allowance | 1,000 requests | Rolling 24 hours |
/api/ask — per IP | 30 requests | 10 minutes |
| Key creation — per IP | 20 keys | 1 hour |
| Signup — per IP | 5 attempts | 1 hour |
The daily allowance is configurable per deployment. When it is exhausted the API answers:
{
"error": "rate_limited",
"message": "Daily request allowance reached for this key."
}
Give each workload its own key. A burst on your reporting job will then never starve your
production traffic.
Credits
Generative endpoints consume credits from the account balance; plain question answering and voice planning are effectively free within the rate limits. New accounts begin with 5,000 credits.
| Situation | Behaviour |
|---|---|
| Credits remaining | Request proceeds and the cost is settled after generation. |
| Credits exhausted | Generative routes answer 402 before doing any work. |
| Provider unreachable | The engine falls back to its local knowledge base instead of failing. |
Recommended retry strategy
- Retry
429and5xxwith exponential backoff plus jitter. - Honour the daily allowance — do not hammer a key that has hit its cap; rotate or upgrade.
- Never retry
400,401,402or403; fix the request instead. - Log the
errorcode and the endpoint — those two fields are enough to diagnose almost everything.
Getting help
If an error is not covered here, include the endpoint, the status code and the timestamp in your message and contact the team.