Errors and close codes
When something goes wrong, the connection or the API tells you with a numeric code. This page lists what each one means and what to do.
WebSocket codes
The server sends a pusher:error event, and for the serious ones also closes the connection with the same code.
| Code | Message | What to do |
|---|---|---|
4001 | App key … does not exist | The key is wrong or the app was deleted. Copy the key from your app's Overview. |
4003 | The app is not enabled | The app is paused. Look at the banner on the app's page in the dashboard for the reason. |
4009 | Connection not authorized | Authorization failed or timed out. Check your authorization endpoint. |
4100 | The current concurrent connections quota has been reached | You are at your plan's connection limit. Wait for connections to close, or change plan. |
4200 | Server closed. Please reconnect shortly | The server is restarting. Reconnect (the Pusher libraries do this automatically). |
4301 | Varies: client events are off, the name or data is too long, or the rate limit was exceeded | The message says which. See Client events. |
4302 | A server error has occurred | Retry. If it keeps happening, contact support. |
Reconnecting
The Pusher protocol groups codes by what a client should do, and the official libraries follow it:
- 4000 to 4099: do not reconnect. Fix the cause first (wrong key, paused app).
- 4100 to 4199: reconnect, but back off.
- 4200 to 4299: reconnect right away.
- 4300 to 4399: the connection stays open; handle the error and carry on.
HTTP API errors
The HTTP API answers 200 and puts the failure in the body, see HTTP API.
code in the body | Cause |
|---|---|
400 | Malformed or incomplete body, or more than 10 events in a batch |
401 | The signature does not match |
404 | Unknown app id |
413 | Event data larger than your plan allows |
429 | Over your publish or read rate, or the app is paused |
Troubleshooting
The client never connects. Check the WebSocket in your browser's network tab. A 4001 means a wrong key. If there is no response at all, check the host, port and whether you set forceTLS to match (a secure deployment needs wss).
Publishing "works" but nothing arrives. The API reports errors in the body. Print what your library returns and look for error. A 401 is almost always the wrong secret or a secret that was rotated.
A private channel will not subscribe. The browser sends a request to your authorization endpoint; check that it answers 200 with a JSON body from authorizeChannel. A 403 from your own code means your rule refused the user.
Everything just stopped. Open the app in the dashboard. A paused app shows why: a pause by you, or by the service for quota, billing or policy reasons.