Skip to content

Lifecycle and Troubleshooting

How a Feed Stays Alive

  • A feed lives while something watches it. As long as the agent or your code is connected, the feed stays open. Left with nothing connected for about two minutes, it ends by itself. A client that comes back after that learns the feed has ended the next time it renews its access, which can take several minutes.
  • The library keeps the connection fresh for you. It renews its access on a schedule the server sets for each feed, and reconnects automatically after a dropped connection, backing off if connections keep failing.
  • You can stop a feed at any time: with Ctrl-C in the agent, feed.stop() in your code, or the Stop button on the Developer page in Scorbit Console.

Connection Status

Status Meaning
idle Not started yet
connecting Opening the connection
live Receiving updates
reconnecting The connection dropped; the library is reconnecting by itself
ended The feed is over. Nothing more will arrive

Why a Feed Ends

When a feed ends, the library's ended event reports a reason and, when the server ended it, an error with a stable code. The agent logs the same reason before it exits.

What happened reason error.code What to do
Stopped from Scorbit Console, or deleted with its API key or feed token ended feed_not_found Open a new feed if you still need one
Left unwatched past the grace period ended feed_not_found Open a new feed; keep the agent or your code running while you need it
Scorbit switched data feeds off withdrawn data_feeds_switched_off Wait and try again later
The account was suspended, the key that opened it was revoked, or a fixed feed lost a machine withdrawn feed_withdrawn Check the Developer page: your key and access, and the machines in the feed. A client that checks back much later may see ended / feed_not_found instead
The feed token is not valid for this feed unauthorized invalid_feed_token Check the feed_id and feed token you attached with
stop() was called, or the connection could not start stopped Expected when you stop the feed yourself

Nothing more is emitted, and no request runs, once a feed has ended.

Errors When Opening a Feed

Error code Status Cause What to do
invalid_api_key 401 The API key is wrong or revoked Check SCORBIT_API_KEY, or generate a new key
scope_too_large 400 The key covers more than the 50 machines one feed can carry (FeedScopeTooLargeError) Open the feed with a list of up to 50 machines
feed_limit_reached 400 Your account already runs 2 live feeds (FeedLimitReachedError) Stop a feed from the Developer page, or wait for an unwatched one to end
machines_unavailable 403 A machine you listed is outside the key's scope or not your account's Run npx @scorbit/feed machines to see what the key covers
data_feed_suspended 403 Data feed access is suspended on your account Contact Scorbit
data_feeds_unavailable 503 Data feeds are temporarily switched off The library makes up to four attempts over a few seconds, then reports it. Try again later
api_key_required, feed_token_required 403 The wrong credential was used for this call Use the API key to open feeds and the feed token to attach
(any) 429 Too many requests; see Rate Limits Wait as long as the Retry-After header says, then try again

Generating a key in Scorbit Console can also report api_key_limit_reached (you already have five keys: revoke one first), developer_terms_not_accepted or developer_terms_changed (accept the current Developer Terms). These never affect opening a feed with a key you already have.

Account suspension also blocks listing what your key covers (data_feed_suspended).

In your code, branch on error.code, never on the message text: messages may be reworded, codes will not.

Rate Limits

Action Limit
Generating API keys 10 per hour per account
Listing, scoping and revoking keys 60 per minute
Opening, changing and deleting feeds 30 per minute per account
Listing what a key covers (machines) 60 per minute
Renewing a feed's access (automatic) 30 per minute per feed

A request over a limit is answered 429, with a Retry-After header saying how long to wait.

  • Opening a feed or listing what a key covers fails straight away with 429. Wait for Retry-After before trying again. The agent reports the error and exits.
  • Renewing a running feed's access is retried automatically for as long as the feed runs, never sooner than Retry-After asks.
  • Deleting a feed (feed.stop()) makes up to four attempts, and reports a 429 at once if Retry-After asks for more than 30 seconds. If deleting fails, feed.stop() rejects after it has already disconnected: call it again later, press Stop on the feed in Scorbit Console, or let the feed end by itself about two minutes after nothing is connected. Until then it counts toward your two live feeds.

Common Problems

The overlay in OBS stays blank or shows a ring that never fills. Check that the agent is still running in its terminal, and that the browser source URL is exactly http://127.0.0.1:8787/. Open the same address in a normal browser to confirm.

npx scorbit-feed runs something else. Run the agent as npx @scorbit/feed. Without a local install, the bare scorbit-feed name resolves to a different, unrelated package.

A page opened from disk can't read the agent. Pages opened from disk (file://) are refused by default. Serve the page with --static instead. --allow-file-origin also works, but it lets sandboxed iframes on any website read the feed too. See The Agent.

A machine is missing from the feed. Run npx @scorbit/feed machines to list what your key covers. A machine your account no longer owns or operates is left out. To include a new machine automatically, use a venue-scoped key and open the feed without listing machines.

The agent exits on its own. Either the feed ended or it could not be opened. The agent logs the reason or error code before it exits: look it up in Why a Feed Ends or Errors When Opening a Feed. For a display that runs all day, see Running It Unattended.

feed_limit_reached right after a crash or a closed terminal. A feed whose agent was killed, rather than stopped with Ctrl-C, keeps counting toward your two live feeds until it ends by itself about two minutes later. Wait two minutes, or press Stop on it in the Live data feeds section of the Developer page.

scope_too_large when starting the agent. Your key covers more than 50 machines. Start the agent with --machines and a list of up to 50 machine uuids.