Errors
HTTP status codes
API errors come back as {"error":"<what went wrong>"} with one of these statuses.
| Status | Meaning | What to do |
|---|---|---|
400 |
The request is invalid, for example a bad room ID or a missing field. | Fix the request. The error text says what's wrong. |
401 |
The API key is missing or wrong. | Check the Authorization: Bearer header. Deleted keys stop working within 15 seconds. |
403 |
Not allowed, for example recording, streaming or agents on the free plan. | Add credit, or check the participant's permissions. |
404 |
That room, recording or key doesn't exist. | |
409 |
Conflicts with the current state, for example already recording, or deleting your last API key. | |
429 |
A monthly allowance is used up, or you're sending too many requests. | Add credit, or slow down and retry. |
5xx |
Something went wrong on our side. | Retry with backoff. |
Why someone left a room
The client's left event gives a reason:
| Reason | |
|---|---|
left |
They left on purpose. |
kicked |
A moderator or your backend removed them. |
room-closed |
The room was ended with DELETE /rooms/:roomId. |
room-full |
The room was at its size limit when they tried to join. |
room-locked |
The room is locked and they aren't a moderator. |
denied |
A moderator turned them away from the waiting room. |
unauthorized |
The join token was invalid or expired. See Long calls. |
connection-lost |
Their network was gone for longer than 2 minutes. |
Common problems
No camera or mic prompt. Browsers only allow the camera and mic on https:// pages (and http://localhost). Screen sharing must start from a click.
No sound from others on the first load. Some browsers block audio until the person has clicked or tapped the page. Join from a button click.
Video is blurry or freezes. The client lowers video quality when the connection is weak and raises it again when it improves. room.on("connection-quality", …) shows who has a poor connection.
A long class ends after 2 hours. Join tokens last 2 hours by default. Refresh them with room.updateToken(), or mint them with a longer ttlSeconds.