Errors & rate limits

Errors are JSON with a detail (and usually message) field.

| Status | Meaning | Fix | |---|---|---| | 400 | Validation failed — the body names each bad field | Fix the fields listed | | 400 "OpenAI models require an API key for usage tracking" | Paid model, no key in body | Add "apikey": "tt…" to the send body | | 401 "Token is invalid or expired" | API key sent as Authorization: Bearer | Use X-API-Key | | 401 | Missing, revoked or expired credentials | Check the key is active | | 402 insufficientbalance | Wallet too low (voice calls, sends) | Top up | | 403 "This website is not allowed to use this bot" | Hosted bot domain lock | Add the domain to Allowed domains | | 403 | You don't own this object / not allowed | Use the owner's credentials | | 404 with a hint mentioning /api/ | You hit a web page, not an endpoint | Add the /api prefix and the trailing slash | | 409 | Duplicate (e.g. webhook idempotency key reused) | Send a new key | | 429 | Rate limited | Back off and retry after the Retry-After header |

Rate limits

Limits apply per user (or per IP for anonymous calls), in short bursts and sustained windows. Chat sending is limited to 30 messages/minute per account; the agent webhook to 60 calls/minute per IP; hosted bots use the per-bot limits their owner configured. On 429, wait and retry with exponential backoff.

CORS

API-key endpoints are not callable from browsers. Hosted-bot endpoints are, from the domains the bot's owner allows.