This chapter describes error and disconnect codes Centrifugo uses in a client protocol, also error codes which a server API can return in response.
Client error codes
Client errors are errors that can be returned to a client in replies to commands. This is specific for bidirectional client protocol only. For example, an error can be returned inside a reply to a subscribe command issued by a client.
Here is the list of Centrifugo built-in client error codes (with proxy feature you have a way to use custom error codes in replies or reuse existing).
Message: "internal server error"
Error Internal means server error, if returned this is a signal that something went wrong with a server itself and client most probably not guilty.
Error Unauthorized says that request is unauthorized.
Message: "unknown channel"
Error Unknown Channel means that channel name does not exist.
Usually this is returned when client uses channel with a namespace which is not defined in Centrifugo configuration.
Message: "permission denied"
Error Permission Denied means that access to resource not allowed.
Method Not Found
Message: "method not found"
Error Method Not Found means that method sent in command does not exist.
Message: "already subscribed"
Error Already Subscribed returned when a client attempts to subscribe to a channel to which it is already subscribed.
In Centrifugo, a client can only have one subscription to a specific channel.
When using client-side subscriptions, this error may signal a bug in the SDK or the SDK being used in a way that was not planned. This error may also be returned by the server when a client tries to subscribe to a channel but is already subscribed to it using server-side subscriptions.
Message: "limit exceeded"
Error Limit Exceeded says that some sort of limit exceeded, server logs should give more detailed information. See also ErrorTooManyRequests which is more specific for rate limiting purposes.
Message: "bad request"
Error Bad Request says that server can not process received data because it is malformed. Retrying request does not make sense.
Message: "not available"
Error Not Available means that resource is not enabled.
For example, this can be returned when trying to access history or presence in a channel that is not configured for having history or presence features.
Message: "token expired"
Error Token Expired indicates that connection token expired. Our SDKs handle it in a special way by updating token.
Error Expired indicates that connection expired (no token involved).
Too Many Requests
Message: "too many requests"
Error Too Many Requests means that server rejected request due to rate limiting strategies.
Message: "unrecoverable position"
Error Unrecoverable Position means that stream does not contain required range of publications to fulfill a history query.
This can happen due to wrong epoch passed.
Client disconnect codes
Client can be disconnected by a Centrifugo server with custom code and string reason. Here is the list of Centrifugo built-in disconnect codes (with proxy feature you have a way to use custom disconnect codes).
We expect that in most situations developers don't need to programmatically deal with handling various disconnect codes, but since Centrifugo sends them and codes shown in server metrics – they are documented. We expect these codes are mostly useful for logs and metrics.
Reason: "connection closed"
DisconnectConnectionClosed is a special Disconnect object used when client connection was closed without any advice from a server side. This can be a clean disconnect, or temporary disconnect of the client due to internet connection loss. Server can not distinguish the actual reason of disconnect.
Non-terminal disconnect codes
Client will reconnect after receiving such codes.
Disconnect Shutdown may be sent when node is going to shut down.
Reason: "internal server error"
DisconnectServerError issued when internal error occurred on server.
Reason: "connection expired"
Reason: "subscription expired"
DisconnectSubExpired issued when client subscription expired.
DisconnectSlow issued when client can't read messages fast enough.
Reason: "write error"
DisconnectWriteError issued when an error occurred while writing to client connection.
Reason: "insufficient state"
DisconnectInsufficientState issued when server detects wrong client position in channel Publication stream. Disconnect allows clien to restore missed publications on reconnect.
Reason: "force reconnect"
DisconnectForceReconnect issued when server disconnects connection for some reason and whants it to reconnect.
Reason: "no pong"
DisconnectNoPong may be issued when server disconnects bidirectional connection due to no pong received to application-level server-to-client pings in a configured time.
Reason: "too many requests"
DisconnectTooManyRequests may be issued when client sends too many commands to a server.
Terminal disconnect codes
Client won't reconnect upon receiving such code.
Reason: "invalid token"
DisconnectInvalidToken issued when client came with invalid token.
Reason: "bad request"
DisconnectBadRequest issued when client uses malformed protocol frames.
DisconnectStale issued to close connection that did not become authenticated in configured interval after dialing.
Reason: "force disconnect"
DisconnectForceNoReconnect issued when server disconnects connection and asks it to not reconnect again.
Reason: "connection limit"
DisconnectConnectionLimit can be issued when client connection exceeds a configured connection limit (per user ID or due to other rule).
Reason: "channel limit"
DisconnectChannelLimit can be issued when client connection exceeds a configured channel limit.
Reason: "inappropriate protocol"
DisconnectInappropriateProtocol can be issued when client connection format can not handle incoming data. For example, this happens when JSON-based clients receive binary data in a channel. This is usually an indicator of programmer error, JSON clients can not handle binary.
Reason: "permission denied"
DisconnectPermissionDenied may be issued when client attempts accessing a server without enough permissions.
Reason: "not available"
DisconnectNotAvailable may be issued when ErrorNotAvailable does not fit message type, for example we issue DisconnectNotAvailable when client sends asynchronous message without MessageHandler set on server side.
Reason: "too many errors"
DisconnectTooManyErrors may be issued when client generates too many errors.