Reference
Errors and limits
Every error the wire returns, what it means and what to do.
| Status | error | Means | Do |
|---|---|---|---|
| 400 | bad request | The body or an event is not valid JSON of the right shape | Fix the request |
| 401 | unauthorized | No token, an expired one, or one we do not recognise | Renew the token (the SDK does) |
| 402 | free_limit_reached | Hobby past 110% of an allowance, or Pro at its spend cap | Upgrade or raise the cap; reads keep working |
| 403 | forbidden | The token is valid but not for this realm, tenant or action | Check the realm prefix and the token’s capabilities |
| 404 | stream not found | The stream does not exist or was deleted | Create it with PUT, or post with a preset |
| 429 | rate_limited | The realm posted faster than its plan’s fair-use rate | Wait Retry-After seconds and resend (the SDK does) |
On the socket#
The socket reports the same errors as { "op": "err", "error": "…" } frames for the op that failed. When the bearer expires without being renewed, the relay closes the socket with code 4401; reconnect with a new token.
Limits#
| Limit | Value |
|---|---|
| Event size for billing | 1 message per started 64 KiB |
| Presence update | Up to 4 KiB counts a tenth of a message |
| One AI answer | 10,000 events or 10 MiB, then it counts again |
| Fair use per realm | Hobby 1,000 events a second, Pro 10,000 (two-second burst) |
| Read page | Up to 500 events; long-poll waits up to 30 s |
| Seat lifetime | 30 to 3,600 seconds, default 900 |
| Subscriptions per connection | 4,096 |