Troubleshooting
Find the close code your client received and read the matching row. Each code has its own entry on the close codes page.
| You see | Most likely cause | What to do |
|---|---|---|
| 4001 | You sent an opcode a client may not send, or a number that is not an opcode | Send only HEARTBEAT, IDENTIFY and RESUME. See opcodes |
| 4002 | A message was not a text frame, was not valid JSON, had the wrong shape, or was over 4,096 bytes | Send one JSON object per text frame |
| 4003 | You sent a heartbeat before identifying, or took longer than 30 seconds to send IDENTIFY | Send IDENTIFY as soon as you receive HELLO |
| 4004 | The token was not accepted | Check that you copied the whole token. If it is lost, create a new one. Do not retry with the same token |
| 4005 | You sent IDENTIFY or RESUME on a connection that was already identifying or identified | Send one of them once per connection |
| 4007 | The seq in RESUME is newer than anything the gateway has sent | Send the sequence number of the last event you processed |
| 4008 | You went past a rate limit | Wait, then reconnect with a longer delay between attempts. See limits |
| 4009 | The server saw no heartbeat for two intervals | Send a heartbeat every interval, and answer the server's own heartbeat |
| 4010 | The token already has 2 connections open | Close one of them, or wait at least 90 seconds for a dropped connection to time out, then reconnect. See tokens |
| 4011 | You fell more than 1,000 events behind | Read events as they arrive, send an accurate last_seq, and resume |
| 4012 | The token was revoked or its account deleted | Create a new token if the account still exists |
| 4013 | The path is not a version the gateway serves | Use /v1 |
| 4014 | Too many open connections from your network | Close some of yours |
| 4015 | The gateway is at capacity or switched off | Wait, then reconnect |
No HELLO, or HTTP 403
If the upgrade is refused with HTTP 403, the request carried an Origin header that is not on the gateway's allow list. The list is empty at launch, so any Origin is refused. Browser clients are not supported. Run your listener from Node.js or Python, which send no Origin header and are not affected.
If the connection opens and closes straight away with no HELLO, the close code is 4008, 4013, 4014 or 4015.
Connected but nothing arrives
A new session only receives events added after it starts. Wait for a new opportunity, or check that your heartbeats are being acknowledged.