Errors & Statuses

xnews separates caller mistakes (thrown immediately) from provider outcomes (reported in result envelopes).

Provider statuses

Every lane uses the same ProviderStatus values:

Status	Meaning	Counts as partial
ok	Returned at least one record	No
empty	Answered with nothing that matches	No
partial	Some of a provider's URLs failed; surviving records are kept (multi-URL fixed feeds, event snapshots with warnings)	Yes
error	Transport, HTTP, timeout, or parse failure	Yes
unsupported	The provider cannot serve this subject (capability or identifier missing); not called	Yes
disabled	A caller precondition is missing (code config): SEC User-Agent, EMMA terms, API key, mirrors	Yes

Feed builders, fetchDataRelease, fetchEventSnapshot, searchWorks, and their …Across variants never throw for a provider failure.

import { buildCompanyNewsFeedResult } from "@xbbg/xnews";

const result = await buildCompanyNewsFeedResult({ ticker: "RGA", companyName: "Reinsurance Group of America" });

for (const provider of result.providers) {
  if (provider.status === "disabled") console.warn("configure:", provider.warnings);
  if (provider.status === "error") console.warn(provider.error?.code, provider.error?.status, provider.error?.url);
}

XnewsFetchError

Standalone fetchers (for example fetchGoogleNews, fetchCotReport, downloadWork) throw XnewsFetchError for transport failures; feed builders catch it into ProviderResult.error.

code	Meaning
config	A precondition failed before any network I/O (missing SEC User-Agent, EMMA terms, API key, invalid URL or maxResponseBytes, no fetch available, unsupported document format)
network	The transport failed, a redirect was refused, or the body exceeded maxResponseBytes
http_status	The upstream answered with a non-success status (status holds it)
timeout	The request and its redirects exceeded timeoutMs
aborted	The caller's signal aborted the request
unknown	Only in ProviderError.code: a failure that did not come from xnews's transport, such as a parse error

import { XnewsFetchError, fetchGoogleNews } from "@xbbg/xnews";

try {
  await fetchGoogleNews("credit spreads", { timeoutMs: 5_000 });
} catch (error) {
  if (error instanceof XnewsFetchError) {
    console.error(error.code, error.status, error.url); // url has credentials and secrets redacted
  } else {
    throw error;
  }
}

Strict mode and watchers

• strict: true on buildCompanyNewsFeed, buildTopicNewsFeed, buildNewsFeed, and buildWatchlistNewsFeed throws Error("… incomplete: …") when any provider produced a warning.
• News watchers throw Error("… unavailable: …") when no provider finishes ok, empty, or partial on a poll, and honor strict.
• Data and event watchers yield failures as results (status: "error" or "disabled"), once per distinct failure, instead of throwing.
• Aborting a watcher's signal during its sleep rejects with the signal's reason.

Inputs that throw immediately

Input	Error
Company subject without ticker, name, or CIK; empty topic query	RangeError
limit that is negative or not an integer	RangeError
Unparseable since/until, or since after until	RangeError
Invalid arXiv category	XnewsFetchError (config), reported as disabled in feeds

Malformed or truncated upstream JSON/XML is an error, never an empty result, and response bytes are never copied into diagnostics.

Related

• Transport & Security
• Data Model