firecrawl 4.9.2 → 4.10.0

package/dist/{chunk-NR7V4IEX.js → chunk-GY35KXDS.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.9.2",
+      version: "4.10.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.cjs

@@ -35,7 +35,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.9.2",
+      version: "4.10.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -115,6 +115,7 @@ __export(index_exports, {
   Firecrawl: () => Firecrawl,
   FirecrawlAppV1: () => FirecrawlApp,
   FirecrawlClient: () => FirecrawlClient,
+  JobTimeoutError: () => JobTimeoutError,
   SdkError: () => SdkError,
   default: () => index_default
 });
@@ -222,12 +223,29 @@ var SdkError = class extends Error {
   status;
   code;
   details;
-  constructor(message, status, code, details) {
+  jobId;
+  constructor(message, status, code, details, jobId) {
     super(message);
     this.name = "FirecrawlSdkError";
     this.status = status;
     this.code = code;
     this.details = details;
+    this.jobId = jobId;
+  }
+};
+var JobTimeoutError = class extends SdkError {
+  timeoutSeconds;
+  constructor(jobId, timeoutSeconds, jobType = "batch") {
+    const jobTypeLabel = jobType === "batch" ? "batch scrape" : "crawl";
+    super(
+      `${jobTypeLabel.charAt(0).toUpperCase() + jobTypeLabel.slice(1)} job ${jobId} did not complete within ${timeoutSeconds} seconds`,
+      void 0,
+      "JOB_TIMEOUT",
+      void 0,
+      jobId
+    );
+    this.name = "JobTimeoutError";
+    this.timeoutSeconds = timeoutSeconds;
   }
 };
 
@@ -303,6 +321,27 @@ function normalizeAxiosError(err, action) {
   const code = body?.code || err.code;
   throw new SdkError(message, status, code, body?.details ?? body);
 }
+function isRetryableError(err) {
+  if (err instanceof JobTimeoutError) {
+    return false;
+  }
+  if (err instanceof SdkError || err && typeof err === "object" && "status" in err) {
+    const status = err.status;
+    if (status && status >= 400 && status < 500) {
+      return false;
+    }
+    if (status && status >= 500) {
+      return true;
+    }
+  }
+  if (err?.isAxiosError && !err.response) {
+    return true;
+  }
+  if (err?.code === "ECONNABORTED" || err?.message?.includes("timeout")) {
+    return true;
+  }
+  return true;
+}
 
 // src/v2/methods/scrape.ts
 async function scrape(http, url, options) {
@@ -535,10 +574,28 @@ async function cancelCrawl(http, jobId) {
 async function waitForCrawlCompletion(http, jobId, pollInterval = 2, timeout) {
   const start = Date.now();
   while (true) {
-    const status = await getCrawlStatus(http, jobId);
-    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    try {
+      const status = await getCrawlStatus(http, jobId);
+      if (["completed", "failed", "cancelled"].includes(status.status)) {
+        return status;
+      }
+    } catch (err) {
+      if (!isRetryableError(err)) {
+        if (err instanceof SdkError) {
+          const errorWithJobId = new SdkError(
+            err.message,
+            err.status,
+            err.code,
+            err.details,
+            jobId
+          );
+          throw errorWithJobId;
+        }
+        throw err;
+      }
+    }
     if (timeout != null && Date.now() - start > timeout * 1e3) {
-      throw new Error(`Crawl job ${jobId} did not complete within ${timeout} seconds`);
+      throw new JobTimeoutError(jobId, timeout, "crawl");
     }
     await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
   }
@@ -677,10 +734,28 @@ async function getBatchScrapeErrors(http, jobId) {
 async function waitForBatchCompletion(http, jobId, pollInterval = 2, timeout) {
   const start = Date.now();
   while (true) {
-    const status = await getBatchScrapeStatus(http, jobId);
-    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    try {
+      const status = await getBatchScrapeStatus(http, jobId);
+      if (["completed", "failed", "cancelled"].includes(status.status)) {
+        return status;
+      }
+    } catch (err) {
+      if (!isRetryableError(err)) {
+        if (err instanceof SdkError) {
+          const errorWithJobId = new SdkError(
+            err.message,
+            err.status,
+            err.code,
+            err.details,
+            jobId
+          );
+          throw errorWithJobId;
+        }
+        throw err;
+      }
+    }
     if (timeout != null && Date.now() - start > timeout * 1e3) {
-      throw new Error(`Batch scrape job ${jobId} did not complete within ${timeout} seconds`);
+      throw new JobTimeoutError(jobId, timeout, "batch");
     }
     await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
   }
@@ -764,6 +839,7 @@ function prepareAgentPayload(args) {
   }
   if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
   if (args.maxCredits !== null && args.maxCredits !== void 0) body.maxCredits = args.maxCredits;
+  if (args.strictConstrainToURLs !== null && args.strictConstrainToURLs !== void 0) body.strictConstrainToURLs = args.strictConstrainToURLs;
   return body;
 }
 async function startAgent(http, args) {
@@ -2809,5 +2885,6 @@ var index_default = Firecrawl;
   Firecrawl,
   FirecrawlAppV1,
   FirecrawlClient,
+  JobTimeoutError,
   SdkError
 });

package/dist/index.d.cts

@@ -531,7 +531,12 @@ declare class SdkError extends Error {
     status?: number;
     code?: string;
     details?: unknown;
-    constructor(message: string, status?: number, code?: string, details?: unknown);
+    jobId?: string;
+    constructor(message: string, status?: number, code?: string, details?: unknown, jobId?: string);
+}
+declare class JobTimeoutError extends SdkError {
+    timeoutSeconds: number;
+    constructor(jobId: string, timeoutSeconds: number, jobType?: 'batch' | 'crawl');
 }
 interface QueueStatusResponse$1 {
     success: boolean;
@@ -587,6 +592,7 @@ declare function prepareAgentPayload(args: {
     schema?: Record<string, unknown> | ZodTypeAny;
     integration?: string;
     maxCredits?: number;
+    strictConstrainToURLs?: boolean;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -1720,4 +1726,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts

@@ -531,7 +531,12 @@ declare class SdkError extends Error {
     status?: number;
     code?: string;
     details?: unknown;
-    constructor(message: string, status?: number, code?: string, details?: unknown);
+    jobId?: string;
+    constructor(message: string, status?: number, code?: string, details?: unknown, jobId?: string);
+}
+declare class JobTimeoutError extends SdkError {
+    timeoutSeconds: number;
+    constructor(jobId: string, timeoutSeconds: number, jobType?: 'batch' | 'crawl');
 }
 interface QueueStatusResponse$1 {
     success: boolean;
@@ -587,6 +592,7 @@ declare function prepareAgentPayload(args: {
     schema?: Record<string, unknown> | ZodTypeAny;
     integration?: string;
     maxCredits?: number;
+    strictConstrainToURLs?: boolean;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -1720,4 +1726,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-NR7V4IEX.js";
+} from "./chunk-GY35KXDS.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -104,12 +104,29 @@ var SdkError = class extends Error {
   status;
   code;
   details;
-  constructor(message, status, code, details) {
+  jobId;
+  constructor(message, status, code, details, jobId) {
     super(message);
     this.name = "FirecrawlSdkError";
     this.status = status;
     this.code = code;
     this.details = details;
+    this.jobId = jobId;
+  }
+};
+var JobTimeoutError = class extends SdkError {
+  timeoutSeconds;
+  constructor(jobId, timeoutSeconds, jobType = "batch") {
+    const jobTypeLabel = jobType === "batch" ? "batch scrape" : "crawl";
+    super(
+      `${jobTypeLabel.charAt(0).toUpperCase() + jobTypeLabel.slice(1)} job ${jobId} did not complete within ${timeoutSeconds} seconds`,
+      void 0,
+      "JOB_TIMEOUT",
+      void 0,
+      jobId
+    );
+    this.name = "JobTimeoutError";
+    this.timeoutSeconds = timeoutSeconds;
   }
 };
 
@@ -185,6 +202,27 @@ function normalizeAxiosError(err, action) {
   const code = body?.code || err.code;
   throw new SdkError(message, status, code, body?.details ?? body);
 }
+function isRetryableError(err) {
+  if (err instanceof JobTimeoutError) {
+    return false;
+  }
+  if (err instanceof SdkError || err && typeof err === "object" && "status" in err) {
+    const status = err.status;
+    if (status && status >= 400 && status < 500) {
+      return false;
+    }
+    if (status && status >= 500) {
+      return true;
+    }
+  }
+  if (err?.isAxiosError && !err.response) {
+    return true;
+  }
+  if (err?.code === "ECONNABORTED" || err?.message?.includes("timeout")) {
+    return true;
+  }
+  return true;
+}
 
 // src/v2/methods/scrape.ts
 async function scrape(http, url, options) {
@@ -417,10 +455,28 @@ async function cancelCrawl(http, jobId) {
 async function waitForCrawlCompletion(http, jobId, pollInterval = 2, timeout) {
   const start = Date.now();
   while (true) {
-    const status = await getCrawlStatus(http, jobId);
-    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    try {
+      const status = await getCrawlStatus(http, jobId);
+      if (["completed", "failed", "cancelled"].includes(status.status)) {
+        return status;
+      }
+    } catch (err) {
+      if (!isRetryableError(err)) {
+        if (err instanceof SdkError) {
+          const errorWithJobId = new SdkError(
+            err.message,
+            err.status,
+            err.code,
+            err.details,
+            jobId
+          );
+          throw errorWithJobId;
+        }
+        throw err;
+      }
+    }
     if (timeout != null && Date.now() - start > timeout * 1e3) {
-      throw new Error(`Crawl job ${jobId} did not complete within ${timeout} seconds`);
+      throw new JobTimeoutError(jobId, timeout, "crawl");
     }
     await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
   }
@@ -559,10 +615,28 @@ async function getBatchScrapeErrors(http, jobId) {
 async function waitForBatchCompletion(http, jobId, pollInterval = 2, timeout) {
   const start = Date.now();
   while (true) {
-    const status = await getBatchScrapeStatus(http, jobId);
-    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    try {
+      const status = await getBatchScrapeStatus(http, jobId);
+      if (["completed", "failed", "cancelled"].includes(status.status)) {
+        return status;
+      }
+    } catch (err) {
+      if (!isRetryableError(err)) {
+        if (err instanceof SdkError) {
+          const errorWithJobId = new SdkError(
+            err.message,
+            err.status,
+            err.code,
+            err.details,
+            jobId
+          );
+          throw errorWithJobId;
+        }
+        throw err;
+      }
+    }
     if (timeout != null && Date.now() - start > timeout * 1e3) {
-      throw new Error(`Batch scrape job ${jobId} did not complete within ${timeout} seconds`);
+      throw new JobTimeoutError(jobId, timeout, "batch");
     }
     await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
   }
@@ -646,6 +720,7 @@ function prepareAgentPayload(args) {
   }
   if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
   if (args.maxCredits !== null && args.maxCredits !== void 0) body.maxCredits = args.maxCredits;
+  if (args.strictConstrainToURLs !== null && args.strictConstrainToURLs !== void 0) body.strictConstrainToURLs = args.strictConstrainToURLs;
   return body;
 }
 async function startAgent(http, args) {
@@ -1258,7 +1333,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-647PIJ6T.js");
+      const packageJson = await import("./package-THA2MQX4.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -2690,6 +2765,7 @@ export {
   Firecrawl,
   FirecrawlApp as FirecrawlAppV1,
   FirecrawlClient,
+  JobTimeoutError,
   SdkError,
   index_default as default
 };

package/dist/{package-647PIJ6T.js → package-THA2MQX4.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-NR7V4IEX.js";
+} from "./chunk-GY35KXDS.js";
 export default require_package();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.9.2",
+  "version": "4.10.0",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/v2/methods/agent.ts

@@ -10,6 +10,7 @@ function prepareAgentPayload(args: {
   schema?: Record<string, unknown> | ZodTypeAny;
   integration?: string;
   maxCredits?: number;
+  strictConstrainToURLs?: boolean;
 }): Record<string, unknown> {
   const body: Record<string, unknown> = {};
   if (args.urls) body.urls = args.urls;
@@ -21,6 +22,7 @@ function prepareAgentPayload(args: {
   }
   if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
   if (args.maxCredits !== null && args.maxCredits !== undefined) body.maxCredits = args.maxCredits;
+  if (args.strictConstrainToURLs !== null && args.strictConstrainToURLs !== undefined) body.strictConstrainToURLs = args.strictConstrainToURLs;
   return body;
 }
 

package/src/v2/methods/batch.ts

@@ -5,11 +5,13 @@ import {
   type Document,
   type BatchScrapeOptions,
   type PaginationConfig,
+  JobTimeoutError,
+  SdkError,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { ensureValidScrapeOptions } from "../utils/validation";
 import { fetchAllPages } from "../utils/pagination";
-import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
+import { normalizeAxiosError, throwForBadResponse, isRetryableError } from "../utils/errorHandler";
 
 export async function startBatchScrape(
   http: HttpClient,
@@ -115,12 +117,37 @@ export async function getBatchScrapeErrors(http: HttpClient, jobId: string): Pro
 
 export async function waitForBatchCompletion(http: HttpClient, jobId: string, pollInterval = 2, timeout?: number): Promise<BatchScrapeJob> {
   const start = Date.now();
+
   while (true) {
-    const status = await getBatchScrapeStatus(http, jobId);
-    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    try {
+      const status = await getBatchScrapeStatus(http, jobId);
+
+      if (["completed", "failed", "cancelled"].includes(status.status)) {
+        return status;
+      }
+    } catch (err: any) {
+      // Don't retry on permanent errors (4xx) - re-throw immediately with jobId context
+      if (!isRetryableError(err)) {
+        // Create new error with jobId for better debugging (non-retryable errors like 404)
+        if (err instanceof SdkError) {
+          const errorWithJobId = new SdkError(
+            err.message,
+            err.status,
+            err.code,
+            err.details,
+            jobId
+          );
+          throw errorWithJobId;
+        }
+        throw err;
+      }
+      // Otherwise, retry after delay - error might be transient (network issue, timeout, 5xx, etc.)
+    }
+
     if (timeout != null && Date.now() - start > timeout * 1000) {
-      throw new Error(`Batch scrape job ${jobId} did not complete within ${timeout} seconds`);
+      throw new JobTimeoutError(jobId, timeout, 'batch');
     }
+    
     await new Promise((r) => setTimeout(r, Math.max(1000, pollInterval * 1000)));
   }
 }

package/src/v2/methods/crawl.ts

@@ -6,10 +6,12 @@ import {
   type Document,
   type CrawlOptions,
   type PaginationConfig,
+  JobTimeoutError,
+  SdkError,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { ensureValidScrapeOptions } from "../utils/validation";
-import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
+import { normalizeAxiosError, throwForBadResponse, isRetryableError } from "../utils/errorHandler";
 import type { HttpClient as _Http } from "../utils/httpClient";
 import { fetchAllPages } from "../utils/pagination";
 
@@ -114,12 +116,37 @@ export async function cancelCrawl(http: HttpClient, jobId: string): Promise<bool
 
 export async function waitForCrawlCompletion(http: HttpClient, jobId: string, pollInterval = 2, timeout?: number): Promise<CrawlJob> {
   const start = Date.now();
+  
   while (true) {
-    const status = await getCrawlStatus(http, jobId);
-    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    try {
+      const status = await getCrawlStatus(http, jobId);
+      
+      if (["completed", "failed", "cancelled"].includes(status.status)) {
+        return status;
+      }
+    } catch (err: any) {
+      // Don't retry on permanent errors (4xx) - re-throw immediately with jobId context
+      if (!isRetryableError(err)) {
+        // Create new error with jobId for better debugging (non-retryable errors like 404)
+        if (err instanceof SdkError) {
+          const errorWithJobId = new SdkError(
+            err.message,
+            err.status,
+            err.code,
+            err.details,
+            jobId
+          );
+          throw errorWithJobId;
+        }
+        throw err;
+      }
+      // Otherwise, retry after delay - error might be transient (network issue, timeout, 5xx, etc.)
+    }
+
     if (timeout != null && Date.now() - start > timeout * 1000) {
-      throw new Error(`Crawl job ${jobId} did not complete within ${timeout} seconds`);
+      throw new JobTimeoutError(jobId, timeout, 'crawl');
     }
+    
     await new Promise((r) => setTimeout(r, Math.max(1000, pollInterval * 1000)));
   }
 }

package/src/v2/types.ts

@@ -631,17 +631,36 @@ export class SdkError extends Error {
   status?: number;
   code?: string;
   details?: unknown;
+  jobId?: string;
   constructor(
     message: string,
     status?: number,
     code?: string,
-    details?: unknown
+    details?: unknown,
+    jobId?: string
   ) {
     super(message);
     this.name = 'FirecrawlSdkError';
     this.status = status;
     this.code = code;
     this.details = details;
+    this.jobId = jobId;
+  }
+}
+
+export class JobTimeoutError extends SdkError {
+  timeoutSeconds: number;
+  constructor(jobId: string, timeoutSeconds: number, jobType: 'batch' | 'crawl' = 'batch') {
+    const jobTypeLabel = jobType === 'batch' ? 'batch scrape' : 'crawl';
+    super(
+      `${jobTypeLabel.charAt(0).toUpperCase() + jobTypeLabel.slice(1)} job ${jobId} did not complete within ${timeoutSeconds} seconds`,
+      undefined,
+      'JOB_TIMEOUT',
+      undefined,
+      jobId
+    );
+    this.name = 'JobTimeoutError';
+    this.timeoutSeconds = timeoutSeconds;
   }
 }
 

package/src/v2/utils/errorHandler.ts

@@ -1,5 +1,5 @@
 import { type AxiosError, type AxiosResponse } from "axios";
-import { SdkError } from "../types";
+import { SdkError, JobTimeoutError } from "../types";
 
 export function throwForBadResponse(resp: AxiosResponse, action: string): never {
   const status = resp.status;
@@ -16,3 +16,36 @@ export function normalizeAxiosError(err: AxiosError, action: string): never {
   throw new SdkError(message, status, code, body?.details ?? body);
 }
 
+export function isRetryableError(err: any): boolean {
+  // JobTimeoutError should never be retried - it's the overall timeout
+  if (err instanceof JobTimeoutError) {
+    return false;
+  }
+  
+  // If it's an SdkError with a status code, check if it's retryable
+  if (err instanceof SdkError || (err && typeof err === 'object' && 'status' in err)) {
+    const status = err.status;
+    // 4xx errors are client errors and shouldn't be retried
+    if (status && status >= 400 && status < 500) {
+      return false; // Don't retry client errors (401, 404, etc.)
+    }
+    // 5xx errors are server errors and can be retried
+    if (status && status >= 500) {
+      return true;
+    }
+  }
+  
+  // Network errors (no response) are retryable
+  if (err?.isAxiosError && !err.response) {
+    return true;
+  }
+  
+  // HTTP timeout errors are retryable (different from JobTimeoutError)
+  if (err?.code === 'ECONNABORTED' || err?.message?.includes('timeout')) {
+    return true;
+  }
+  
+  // Default: retry on unknown errors (safer than not retrying)
+  return true;
+}
+