The count that matters is per WebSocket cluster: your Massive account has a separate allowance on each cluster, and every API key on the account shares it. The cluster part is what people plan around wrongly. A Stocks connection cannot be pointed at Options or Indices, so holding three subscriptions gives you one connection on each of three clusters rather than three you can aim anywhere. One connection then carries every ticker and event type your plan covers on that cluster, with a single documented exception for Options Quotes.
Applies to
- Plans: every paid subscription. Basic, the free tier, has no WebSocket access.
- Feeds: one cluster per URL, and each is counted separately. wss://socket.massive.com/stocks, /options, /indices, /futures, /forex and /crypto.
- Asset classes: Stocks, Options, Indices, Futures, Forex and Crypto.
How many connections your plan includes
Individual subscriptions include one connection on the cluster for the asset class you bought. Business subscriptions include three, and two more can be added at no charge, so five is the point at which additional connections start costing something. If you need more than your plan includes, ask us.
Because the count is per cluster, connections on different clusters do not compete. A Currencies subscription covers both Forex and Crypto, and those are two separate clusters, so streaming both at the same time means one connection open on /forex and one on /crypto rather than two connections drawn from a single pool.
A connection belongs to one cluster
This is the most common surprise. A connection is tied to the subscription that provides it, so holding subscriptions to three asset classes gives you one connection on each of three clusters rather than three connections you can aim wherever you like. If you need two simultaneous Stocks streams, one Stocks subscription is not enough on its own: you need an additional Stocks connection.
That is also why a second connection is worth having even when one is enough for the data. Two consumers that must not affect each other, such as a production service and a research notebook, want their own connections, because a consumer that reads too slowly fills the server-side buffer and gets disconnected.
What happens when you exceed the limit
When you exceed the limit, one of the connections is closed, and which one depends on the cluster. Tested with two connections on one key: on /stocks, /futures, /indices and /forex the older connection was closed and the new one kept streaming; on /options the new connection was refused at its auth and the old one carried on. Either way the closed connection is told why:
[{"ev":"status","status":"max_connections","message":"Maximum number of websocket connections exceeded. You have reached the connection limit for your account. Please contact support at https://massive.com/contact to increase your limit."}]
So a service that reconnects in a loop is competing with itself for one slot. On the clusters where the newcomer wins it will keep knocking its own healthy stream offline, and the symptom looks like random disconnects rather than a limit. If you see max_connections, count the processes connecting to that cluster with any API key on your account before changing anything else.
When the dashboard still shows a connection as active
The connections tab of your dashboard can still show a Massive WebSocket connection as active after your program has stopped, because the tab is not updated in real time. The server's own count is what decides whether a new connection is accepted. On /options, where a connection over the allowance is refused rather than replacing an older one, a new connection is accepted again about 10 to 15 seconds after the old one ends, whether your client closed it or its process was killed.
So after an unexpected disconnect, wait at least 15 seconds before you reconnect. If the new connection is refused with max_connections, wait again rather than retrying at once: the connection that just ended can still be counted during that time. A paused or hung process that is still connected keeps its slot, so check for one before waiting longer.
How to get more connections
Connections cannot be bought in the dashboard today. We add them for you.
- Start a chat at massive.com/contact and say which asset class you need connections for, and how many.
- We add them while you wait and confirm the details with you first.
- Check what you have on the connections tab of your dashboard.
No new API key is needed for an added connection. The allowance belongs to your account rather than to a key, so the key you already use can open every connection you have on that cluster.
The Options Quotes exception
Options Quotes are capped at around a thousand contracts per connection, and a message that would cross the cap is refused in full rather than partially filled. Beyond it you need more connections, which is the one case where the amount you subscribe to, rather than the number of streams you run, is what makes you ask for another.
If you see an error
{"ev":"status","status":"error","message":"not authorized"} arrives in response to a subscribe, not on connect, and means your plan does not cover that feed on that cluster. Authentication succeeds on any cluster, so a successful auth_success is not proof that your key is entitled to the data. Check which subscriptions your key carries before buying anything.
{"ev":"status","status":"auth_failed","message":"authentication failed"} means the key itself was rejected, and the server closes the connection immediately afterwards. Check the key rather than your plan.
Repeated disconnects on a single connection, with no status frame before them, are usually a slow consumer rather than a limit. Read packets off the network immediately into a queue and parse them on another thread.
