Troubleshooting
Checklist
Almost every support thread starts the same way: the stream is open and nothing is arriving. Several different causes look identical from the outside. Work down this list.
| Check | How | If that is it |
|---|---|---|
Does the socket close with 4001 right after opening? | Read the close reason, then GET /v1/account with the same key | missing_api_key: the key never arrived; send it as Authorization: Bearer, X-API-Key or ?api_key=. invalid_api_key: typo or rotated secret. key_revoked: ask whoever issued it |
Does your key have stream? | GET /v1/account | Without it the socket closes with 4003 immediately |
| Are you actually monitoring anyone? | GET /v1/monitor/targets | An empty list means an open socket that will never speak |
| Is real-time delivery active for that account yet? | Same call — look at push_ready | false right after adding is normal; activation usually takes a few minutes. Events for the account are delivered meanwhile, complete, though some may arrive later than usual, so handle them as they come instead of waiting for true. If it stays false for an hour, tell us |
| Did you or we limit the event types? | GET /v1/monitor/targets/{target}, field event_types; then GET /v1/account, field event_types | Empty means every type. A subscription's list is yours: widen it with PATCH /v1/monitor/targets/{target}. The key-wide list was set at your request; ask us to widen it |
| Expecting keyword hits? | GET /v1/keywords, and check keywords:read is on the key | Without the scope, search.match is filtered out before it reaches you |
| Is the account quiet, or invisible? | GET /v1/users/{name}/tweets | X hides some accounts from search and from others' timelines. If we cannot see it, we cannot report it |
| Too many connections? | Close code 4002 | Your plan's max_conns is reached; old sockets may still be held open by a crashed process |
| Added the target after opening the socket? | Wait 30 seconds | An open connection picks up new subscriptions on its next refresh, not instantly |
Getting 429 on REST? | Read X-RateLimit-Remaining and Retry-After | A tight request loop against REST is the usual cause; the stream is not metered, use it instead |
Still stuck: send us any X-Request-Id, or an event id you expected and did not get.