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

StatusCodeMeaningRetry?
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

ScopeLimitWindow
API key — daily allowance1,000 requestsRolling 24 hours
/api/ask — per IP30 requests10 minutes
Key creation — per IP20 keys1 hour
Signup — per IP5 attempts1 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.

SituationBehaviour
Credits remainingRequest proceeds and the cost is settled after generation.
Credits exhaustedGenerative routes answer 402 before doing any work.
Provider unreachableThe engine falls back to its local knowledge base instead of failing.

Recommended retry strategy

  1. Retry 429 and 5xx with exponential backoff plus jitter.
  2. Honour the daily allowance — do not hammer a key that has hit its cap; rotate or upgrade.
  3. Never retry 400, 401, 402 or 403; fix the request instead.
  4. Log the error code 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.