Error Handling

Every failure in Reader surfaces as a typed error. This page covers the mental model; see API Reference - Errors for the full class list.

Everything is typed

All errors extend a base ReaderError class and carry:

code - a stable string like TIMEOUT or NETWORK_ERROR
message - human-readable description
retryable - a boolean telling you whether this is a transient failure worth retrying
url - the URL that failed (when applicable)
toJSON() - structured output for logging

import { ReaderError } from "@vakra-dev/reader";

try {
  await reader.scrape({ urls: [...] });
} catch (err) {
  if (err instanceof ReaderError) {
    console.error({
      code: err.code,
      retryable: err.retryable,
      message: err.message,
      url: err.url,
    });
  }
}

The retryable flag

retryable: true means the error is transient and a retry with the same input might succeed. retryable: false means the error is terminal - retrying won’t help. Examples of retryable errors:

NETWORK_ERROR - connection reset, socket error
TIMEOUT - page took too long to load
PROXY_CONNECTION_ERROR - proxy unreachable
BOT_DETECTED - might pass on retry with a different proxy
EMPTY_CONTENT - page might have been rate-limiting

Examples of non-retryable errors:

INVALID_URL - malformed URL, not going to improve
DNS_ERROR - hostname doesn’t exist
ROBOTS_BLOCKED - robots.txt forbids it
ACCESS_DENIED - 401/403 from the origin
PROXY_EXHAUSTED - all proxy tiers tried and failed
VALIDATION_ERROR - you passed bad options

Proxy tier handling

If a scrape fails with BOT_DETECTED using the standard (datacenter) tier, consider retrying with the premium (residential) tier:

try {
  return await reader.scrape({ urls: [url], proxyTier: "standard" });
} catch (err) {
  if (err.code === "BOT_DETECTED") {
    return await reader.scrape({ urls: [url], proxyTier: "premium" });
  }
  throw err;
}

Non-retryable errors (DNS failure, invalid URL, robots.txt) skip directly to failure without trying another tier. The timeouts are configurable per-request:

await reader.scrape({
  urls: [...],
  hardDeadlineMs: 30000,       // total cap per URL (default: 30s)
  datacenterTimeoutMs: 10000,  // first attempt timeout (default: 10s)
});

Error handling patterns

Simple try/catch

For one-off scripts, wrap the call and log:

try {
  const result = await reader.scrape({ urls: [url] });
  console.log(result.data[0].markdown);
} catch (err) {
  console.error(`Scrape failed: ${err.message}`);
}

Retry on retryable errors

For production code, check the flag:

async function scrapeWithRetry(url, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await reader.scrape({ urls: [url] });
    } catch (err) {
      if (!err.retryable || attempt === maxAttempts - 1) {
        throw err;
      }
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
    }
  }
}

Batch with partial failures

When scraping many URLs, a batch can partially succeed. The result’s batchMetadata.errors array tells you which URLs failed:

const result = await reader.scrape({
  urls: [url1, url2, url3, url4],
  batchConcurrency: 2,
});

console.log(`Success: ${result.batchMetadata.successfulUrls}`);
console.log(`Failed:  ${result.batchMetadata.failedUrls}`);

for (const { url, error } of result.batchMetadata.errors ?? []) {
  console.error(`  ${url}: ${error}`);
}

The successful URLs still come back in result.data. Batch scraping never throws on individual URL failures - only on framework-level errors (browser pool exhausted, invalid options, etc.).

Getting Started

Concepts

Guides

API Reference

Error Handling

Everything is typed

The retryable flag

Proxy tier handling

Error handling patterns

Simple try/catch

Retry on retryable errors

Batch with partial failures

Where to go next

Errors reference

Scraping Engine

​Everything is typed

​The retryable flag

​Proxy tier handling

​Error handling patterns

​Simple try/catch

​Retry on retryable errors

​Batch with partial failures

​Where to go next

Errors reference

Scraping Engine

Everything is typed

The retryable flag

Proxy tier handling

Error handling patterns

Simple try/catch

Retry on retryable errors

Batch with partial failures

Where to go next