HTTP 429 responses from Gitter's message-streaming API under concurrent connections

Short answer

The budget is counted per access token, not per connection. Every connection — an ordinary REST request or a long-lived streaming (SSE) connection — draws from the same token-scoped pool. Opening a stream spends one unit at handshake time; individual events delivered over an already-open stream do not decrement the counter again. Two clients sharing one token therefore share one budget, while two separate tokens get independent budgets.

Confidence caveat: this is the observable model, not a published contract. The public API documentation does not spell out streaming accounting in detail, and the service now runs under GitLab with the API surface explicitly subject to change. Treat any number you observe as a live snapshot of your token rather than a stable guarantee.

How the accounting behaves in practice

• Quota follows the token, so it travels with that token across processes, machines, and IP addresses.
• A stream costs one unit when it is established, not one unit per message delivered.
• Because REST and streaming share the pool, N concurrent room streams reduce what remains for ordinary calls such as GET /v1/rooms.
• Quota-exhaustion 429s appear on new connection attempts — including the SSE handshake — rather than mid-stream.

If a 429 arrives without X-RateLimit-Remaining or X-RateLimit-Reset headers, it probably did not come from Gitter's quota logic. Proxies, corporate middleboxes, and CDNs emit their own 429s, and those are the ones that tend to correlate with concurrency without tracking your token at all.

Confirming it for your token

The headers are the only reliable source. Run this sequence against one token and record X-RateLimit-Remaining at each step.

# 1. baseline
curl -sD - -o /dev/null -H "Authorization: Bearer $TOKEN" \
  https://api.gitter.im/v1/rooms | grep -i x-ratelimit

# 2. open one stream, then re-run the baseline call
curl -N -H "Authorization: Bearer $TOKEN" \
  https://api.gitter.im/v1/rooms/$ROOM_ID/chatMessages

# 3. open a second stream with the same token, re-check again

# 4. repeat step 1 with a second, different token

1. Note remaining before any stream is opened.
2. Open one stream, then re-check. A drop of one unit confirms the per-connection cost.
3. Open a second stream with the same token and re-check. Another drop confirms the shared pool.
4. Repeat with a different token. An unchanged value confirms per-token isolation.

Keep the stream open while you re-check. Whether closing it returns the unit is a separate question worth observing on its own.

The one detail that changes the recommendation

Does the 429 response actually carry X-RateLimit-Remaining: 0? If yes, the fix is token and connection budgeting: one token per client, and a hard cap on concurrent room streams per token. If the 429 has no rate-limit headers, stop tuning the client and inspect the path between you and Gitter — an SSE-aware proxy that buffers, a middlebox that rewrites connections, or a client that reconnects in a tight loop and manufactures its own concurrency.

Latency or dropped events with no 429 at all is a different problem. That points at buffering or parsing, not quota.

Uncertainty to flag

Whether a closed stream refunds its unit, whether IP-based rules apply in some environments, and whether the accounting changed after the GitLab migration are all unverified here. Confirm with the header experiment on the token you actually deploy, and re-run it after any platform change.