WebSocket close codes and Pusher error codes
What each code means and what to do about it: the standard WebSocket close codes (1000–1015) and the Pusher protocol’s error codes (4000–4399), which Hibira and other Pusher-compatible services send too.
Pusher protocol codes
A Pusher server sends a pusher:error message with the code and a reason, then closes the connection with the same code. The range tells the client what to do next.
4000 SSL only
The app accepts only encrypted connections.
What to do: Connect with wss:// (forceTLS: true in pusher-js).
Does not reconnect with the same settings4001 Application does not exist
No app with this key on this host.
What to do: Check the app key and the host (or cluster): a key from one service or region does not work on another.
Does not reconnect with the same settings4003 Application disabled
The app exists but is switched off.
What to do: Turn the app back on in its dashboard, or check the account’s billing.
Does not reconnect with the same settings4004 Over connection quota
The app has as many connections open as its plan allows.
What to do: Wait for other connections to close, close tabs you do not need, or move to a plan with more connections.
Does not reconnect with the same settings4005 Path not found
The URL path is not /app/APP_KEY.
What to do: Check the WebSocket path: proxies and wrong wsPath settings often cause this.
Does not reconnect with the same settings4006 Invalid version string format
The client sent a version the server cannot read.
What to do: Use an official client library, or send protocol=7 in the URL.
Does not reconnect with the same settings4007 Unsupported protocol version
The server does not support the protocol version the client asked for.
What to do: Update the client library; protocol 7 is current.
Does not reconnect with the same settings4008 No protocol version supplied
The URL has no protocol parameter.
What to do: Add ?protocol=7 to the URL, or use an official client library.
Does not reconnect with the same settings4009 Connection is unauthorized
The server refused this connection: on Hibira, most often because the page’s origin is not allowed.
What to do: Add the site’s origin (scheme, host and port) to the app’s allowed origins. The pusher:error message before the close says which check failed.
Does not reconnect with the same settings4100 Over capacity
The server is busy, or too many connections came from one address at once.
What to do: Nothing, in most cases: clients retry with back-off. If it keeps happening, spread out reconnects instead of reconnecting every client at the same moment.
Reconnects with back-off4200 Generic reconnect immediately
The server asked the client to reconnect, for example because it is restarting.
What to do: Nothing: the client reconnects at once.
Reconnects at once4201 Pong reply not received
The server sent a ping and no pong came back in time.
What to do: Usually a sleeping tab or a weak mobile network. If you wrote your own client, answer pusher:ping with pusher:pong.
Reconnects at once4202 Closed after inactivity
The connection was idle for too long.
What to do: Nothing: the client reconnects. Keep the client’s activity timeout below the server’s.
Reconnects at once4301 Client event rejected due to rate limit
A client event was dropped because the connection sent too many too fast (or, on Hibira, the daily message quota ran out). The connection stays open.
What to do: Send fewer client events per second, for example by throttling typing or cursor events.
Connection stays open
Standard WebSocket codes
These come from the WebSocket standard (RFC 6455) and apply to any WebSocket server.
1000 Normal Closure
The connection was closed on purpose, and the work is done.
What to do: Nothing to fix.
1001 Going Away
The page was closed or reloaded, or the server is shutting down.
What to do: Nothing to fix; reconnect when the page or server is back.
1002 Protocol Error
One side sent a frame that breaks the WebSocket protocol.
What to do: Look for a proxy that rewrites traffic, or a client and server library that disagree.
1003 Unsupported Data
A message of a type the other side cannot accept, such as binary to a text-only server.
What to do: Send the type the server expects (Pusher servers take JSON text).
1005 No Status Received
The close frame had no code. Browsers report this; it is never sent.
What to do: Nothing on its own; look at what the server logged when it closed.
1006 Abnormal Closure
The connection dropped without a close frame: the network, TLS, a proxy or the server ended it. Browsers report this; it is never sent.
What to do: Check the host and port, wss:// against ws://, the certificate, and proxy or load balancer idle timeouts (send heartbeats more often than they cut idle connections). In the browser, the console usually shows the cause.
1007 Invalid Frame Payload Data
A text message was not valid UTF-8.
What to do: Encode text as UTF-8, or send it as binary.
1008 Policy Violation
The server refused the message or connection under its own rules, such as authentication or origin checks.
What to do: Check the server’s rules and its close reason.
1009 Message Too Big
A message was larger than the other side accepts.
What to do: Send smaller messages, or split large ones.
1010 Mandatory Extension
The client needed an extension that the server did not agree to.
What to do: Turn off the extension on the client, or enable it on the server.
1011 Internal Error
The server hit an unexpected error.
What to do: Check the server logs; reconnect with back-off.
1012 Service Restart
The server is restarting.
What to do: Reconnect after a short, random delay.
1013 Try Again Later
The server is overloaded for now.
What to do: Reconnect with back-off.
1014 Bad Gateway
A gateway or proxy got a bad answer from the server behind it.
What to do: Check the server behind the proxy.
1015 TLS Handshake
The TLS handshake failed, for example on a certificate the client does not trust. Browsers report this; it is never sent.
What to do: Check the certificate chain, its host names and its expiry date.
Code ranges
- 1000–2999: reserved for the WebSocket standard; this one is not assigned.
- 3000–3999: registered for libraries and frameworks; check the one you use.
- 4000–4099: a Pusher error after which the client does not reconnect with the same settings.
- 4100–4199: a Pusher error after which the client reconnects with back-off.
- 4200–4299: a Pusher error after which the client reconnects at once.
- 4300–4399: a Pusher error that leaves the connection open.
- 4000–4999: private use. The application or service that sent it defines what it means.
Subscription errors
A failed subscription to a private or presence channel does not close the connection: the client gets pusher:subscription_error instead. AuthError there almost always means the signature from your auth endpoint does not match, because the secret, socket ID, channel name or channel_data differs from what was signed.
Test a connection with the WebSocket tester → · Message size and other limits →