Error Codes

Errors are reported in two ways depending on when they occur:

Before the connection is accepted: The server sends a WebSocket close frame with a numeric close code.
After the connection is accepted: The server sends a JSON error message over the open connection.

Close Codes

These are returned as part of the WebSocket close handshake. Your client will see them in the onclose event.

Code	Meaning	When
4401	Unauthorized	Missing, malformed, or invalid API key
1013	Try Again Later	Connection limit exceeded for your account
1008	Policy Violation	Generic server-initiated close after sending an error message
1012	Service Restart	Server restarting; reconnect immediately

Handling Close Codes

ws.onclose = (event) => {
  switch (event.code) {
    case 4401:
      console.error("Invalid API key. Check your credentials.");
      break;
    case 1013:
      console.warn("Connection limit reached. Retrying in 5s...");
      setTimeout(reconnect, 5000);
      break;
    case 1012:
      console.info("Server restarting. Reconnecting...");
      reconnect();
      break;
    default:
      console.info(`Connection closed: ${event.code} ${event.reason}`);
      reconnect();
  }
};

Error Messages

These are sent as JSON messages over an open connection. The connection remains open -- you can fix the issue and retry.

{
  "op": "error",
  "code": "BAD_STREAM",
  "message": "Unknown stream 'foo'. Allowed: clusters"
}

Error Code Reference

Code	Description	Resolution
`BAD_JSON`	The message you sent is not valid JSON	Check your JSON serialization
`BAD_ARGS`	Required fields are missing or the argument combination is invalid	Check the required fields for the operation
`BAD_MODE`	The `mode` field must be `add` or `replace`	Use `"add"` or `"replace"`
`BAD_STREAM`	The `stream` value is not recognized	Use a supported stream name (see Streams)
`BAD_NETWORK`	The `network` value is not recognized	Use a supported network ID (see Overview)
`BAD_ADDRESS`	The `address` is not a valid format for the specified network	Check address format (e.g. base58 for Solana, hex for EVM)
`CONN_LIMIT`	You've exceeded your plan's concurrent connection limit	Close unused connections or upgrade your plan
`TOPIC_LIMIT`	You've exceeded your plan's topic subscription limit	Unsubscribe from topics you no longer need, or upgrade your plan
`OP_UNKNOWN`	The `op` value is not recognized	Use a valid operation: `subscribe`, `unsubscribe`, or `ping`