Error codes
Connection and channel errors
thunderclapJS reports these codes through error events: connection-level errors on the client (thunderclap.on("error")), channel errors on the channel (channel.on("error")).
| Code | Scope | Meaning | What happens |
|---|---|---|---|
4001 | Connection | Unknown app key | Fails for good: check THUNDERCLAP_KEY |
4003 | Connection | The app is suspended | Fails for good until the app is reactivated |
4009 | Connection | Connection token invalid or expired | Fails for good: check the token your backend issues |
4100 | Connection | Over capacity, or too many connections opened at once for the app | Retries with backoff |
4101 | Connection | The app reached its plan's connection limit (Spark) | Retries with backoff, connecting once a place frees up |
4200 | Connection | Reconnect now (maintenance or rebalancing) | Reconnects at once, automatically |
4300 | Channel | Malformed frame | The connection stays open |
4301 | Channel | Invalid channel name | The subscription is refused |
4302 | Channel | Not authorized for this private or presence channel (presence also needs a user id) | The subscription is refused |
4303 | Channel | Too many subscriptions on one connection (100) | The subscription is refused |
4304 | Channel | Internal error while handling the channel | Try subscribing again |
4305 | Channel | The presence channel is full (100 members) | The subscription is refused |
4306 | Channel | A client event was refused: disabled for the app, public channel, not subscribed, bad name, too large or too many | The event is dropped |
Codes from 4000 to 4099 are final: the client moves to the failed state and stops reconnecting. Codes from 4100 to 4199 are retried with backoff, 4200 to 4299 reconnect at once, and 4300 and up concern one channel while the connection stays open.
Server SDK errors
@thunderclapjs/server throws a ThunderclapApiError with the HTTP status and a message:
| Status | Meaning |
|---|---|
400 | Invalid input: channel or event name, data too large, too many channels or events |
401 | Wrong app id or secret, or the app is suspended |
429 | Too many requests: either the app used up its plan's messages for the month (Spark), which resumes next month or once the organisation upgrades, or it sent more than 1,000 requests a second, which resumes after the Retry-After delay |
5xx | Temporary failure: retry |
Webhook verification throws a ThunderclapWebhookError instead. See the server reference.