Errors - Bridgly

The result union

No SDK method throws for API or network errors. Every scraping method returns an ApiResult, a discriminated union you narrow on the type field:

type ApiResult<T> =
  | { type: 'success'; data: T; timeMs: number; creditsCost: number }
  | { type: 'error'; status: number; message: string };

Checking type narrows the rest of the object — in the success branch data, timeMs, and creditsCost are all available and typed; in the error branch you get status and message.

const res = await client.x.getUser({ handle: 'jack' });

if (res.type === 'error') {
  // handle and return early
  console.error(`Bridgly error ${res.status}: ${res.message}`);
  return;
}

// res.data is fully typed from here on
console.log(res.data);

Input validation

The SDK validates request inputs with Zod before making an HTTP request. Invalid inputs, such as an unsupported sort value or a count above the endpoint’s limit, can throw a Zod validation error. No request is sent and no credits are consumed when this validation fails. The client constructor also throws if apiKey is missing or empty. These local errors are separate from the typed results returned for API and network failures.

Error status codes

The error result’s status field normally carries the HTTP status code; 0 indicates a network failure. Branch on it rather than parsing the message string.

Status	Meaning	What to do
`400`	The request failed validation.	Check the field values against the endpoint schema.
`401`	Missing, malformed, or revoked API key.	Verify the key you passed to `new Bridgly(...)`.
`402`	Out of credits.	Top up from the dashboard or with `client.billing.buyCredits`.
`404`	The requested resource wasn’t found.	Confirm the identifier exists and is public.
`429`	A rate limit was exceeded.	Slow down and retry later. See Rate limits.
`500`	The scrape failed unexpectedly.	Retry after a short delay.
`0`	Network error — no HTTP response was received.	Check connectivity; the `message` has the detail.

​The result union

​Input validation

​Error status codes

The result union

Input validation

Error status codes