API errors and limits

Runtime statuses

Socket error codes are on WebSocket and Speech and recognition.

Management statuses

Burst limits

Fixed windows per minute, counted for the whole account and, where the table says so, for each visitor too — a visitor is one address on one site. Over the limit: 429, or a rate_limited error frame on a socket; the credit is not spent and the turn is not run.

A visitor also has a day: 300 chat turns, 300 recognition streams and 30,000 characters of speech. Past it a chat turn gets 429 or rate_limited like any burst, and /tts answers 429 with Speech limit reached for today.

Speech and recognition spend no credit themselves, so an account earns them by its answers: each answered turn adds 2,500 characters of speech and 6 recognition streams to that day’s budget, on top of 20,000 characters and 200 streams a day for what no answer pays for — a spoken greeting, Shukai.speak, a dictation never sent. Past it /tts answers 429 with Speech limit reached for today and /ws/stt sends rate_limited. A sentence replayed from the audio cache costs nothing and is never refused.

The monthly quota and the soft block

Each answered turn costs credits by model, plus the voice surcharge when spoken (Credits and models). The allowance refills on the subscription day; purchased top-ups carry over and are spent after it. At the cap:

• a /message call still returns 200, with the localized limit message as answer and empty lists;
• a socket turn gets limit_reached after start instead of an answer;
• GET /widget/config serves active: false from the next load, so the widget mounts nothing;
• the owner is emailed at 80 % and 100 %.

Before a plan is active the account has an allowance of its own: 50 credits a day and 300 a month, 20,000 characters of speech and 100 recognition streams a day. Past it a turn is answered as at the monthly cap, with a message that the trial allowance is used up, and no email is sent.

A custom front end should treat limit_reached and active: false as «the assistant is away», not as an error.

Per-plan caps

A site create past the plan’s site count and a source create over the page cap are each a 403 whose detail names the cap; a tool or event create over its cap is 400 on scope; both are judged on the resulting count, so nothing already saved is lost on a downgrade — it is marked «not on your plan» and stops being served.

Per-turn caps