firecrawl-common-errors

Diagnose and fix Firecrawl common errors and API response codes. Use when encountering Firecrawl errors, debugging failed scrapes, or troubleshooting crawl job issues. Trigger with phrases like "firecrawl error", "fix firecrawl", "firecrawl not working", "debug firecrawl", "firecrawl 429", "firecrawl 402".

Jump to install

Repository: jeremylongshore/tons-of-skills-marketplace
Last source activity: August 19, 2026 at 12:13
Detected SKILL.md language: English
Stars: 2,677
Forks: 392

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	firecrawl-common-errors
description	Diagnose and fix Firecrawl common errors and API response codes. Use when encountering Firecrawl errors, debugging failed scrapes, or troubleshooting crawl job issues. Trigger with phrases like "firecrawl error", "fix firecrawl", "firecrawl not working", "debug firecrawl", "firecrawl 429", "firecrawl 402".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.11.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","firecrawl","debugging"]
compatibility	Designed for Claude Code

Firecrawl Common Errors

Overview

Quick-reference diagnostic guide for the most common Firecrawl API errors. Covers HTTP status codes, SDK exceptions, empty content, and crawl job failures with concrete fixes.

Prerequisites

Firecrawl SDK installed (@mendable/firecrawl-js)
FIRECRAWL_API_KEY environment variable set
Access to error logs or console output

Error Reference

401 Unauthorized — Invalid API Key

Error: Unauthorized. Invalid API key.

Cause: API key is missing, malformed, or revoked.

set -euo pipefail
# Verify key is set and starts with fc-
echo "Key prefix: ${FIRECRAWL_API_KEY:0:3}"

# Test directly
curl -s https://api.firecrawl.dev/v1/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["markdown"]}' | jq .success

Fix: Regenerate key at firecrawl.dev/app. Ensure it starts with fc-.

402 Payment Required — Credits Exhausted

Error: Payment required. You have exceeded your credit limit.

Cause: Monthly or plan credits are used up.

set -euo pipefail
# Check remaining credits
curl -s https://api.firecrawl.dev/v1/team/credits \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" | jq .

Fix: Upgrade plan or wait for monthly credit reset. Failed requests do not consume credits.

429 Too Many Requests — Rate Limited

Error: Rate limit exceeded. Retry after X seconds.

Cause: Too many concurrent requests or requests per minute.

// Fix: implement exponential backoff
  () {
   ( i = ; i < retries; i++) {
     {
        firecrawl.(url, { : [] });
    }  (: ) {
       (err. !==  || i === retries - )  err;
       delay =  * .(, i);
      .();
        ( (r, delay));
    }
  }
}

const result = await firecrawl.scrapeUrl("https://spa-app.com");
console.log(result.markdown); // "" or just nav text

// Fix: add waitFor and use actions for dynamic content
const result = await firecrawl.scrapeUrl("https://spa-app.com", {
  formats: ["markdown"],
  waitFor: 5000,  // wait 5s for JS rendering
  onlyMainContent: true,
});

const crawl = await firecrawl.crawlUrl("https://example.com/docs", {
  includePaths: ["/api/*"],
});
// crawl.data is empty

// Fix: ensure start URL matches include patterns
const crawl = await firecrawl.crawlUrl("https://example.com", {
  includePaths: ["/docs/*", "/api/*"],  // start URL must match too
  limit: 50,
});

const status = await firecrawl.checkCrawlStatus(jobId);
// status.status === "scraping" for >10 minutes

// Fix: set timeout and fall back to individual scrapes
const TIMEOUT_MS = 600000; // 10 minutes
const deadline = Date.now() + TIMEOUT_MS;

while (Date.now() < deadline) {
  const status = await firecrawl.checkCrawlStatus(jobId);
  if (status.status === "completed") return status;
  if (status.status === "failed") throw new Error(status.error);
  await new Promise(r => setTimeout(r, 5000));
}
throw new Error("Crawl timed out — try reducing limit or using scrapeUrl");

Error: Cannot find module '@firecrawl/sdk'

set -euo pipefail
# The correct package is @mendable/firecrawl-js
npm install @mendable/firecrawl-js

set -euo pipefail
# 1. Check Firecrawl API health
curl -s https://api.firecrawl.dev/v1/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["markdown"]}' | jq '{success, markdown_length: (.markdown | length)}'

# 2. Verify SDK version
npm list @mendable/firecrawl-js 2>/dev/null

# 3. Check env var
env | grep FIRECRAWL

Status	Meaning	Retryable	Action
200	Success	N/A	Process result
401	Bad API key	No	Check/rotate key
402	No credits	No	Upgrade or wait for reset
408	Timeout	Yes	Increase timeout, simplify request
429	Rate limited	Yes	Backoff, check Retry-After
500	Server error	Yes	Retry with backoff
503	Service down	Yes	Check status page, retry later

async function safeScrape(url: string) {
  try {
    return await firecrawl.scrapeUrl(url, { formats: ["markdown"] });
  } catch (err: any) {
    const status = err.statusCode;
    if (status === 401) console.error("Invalid API key");
    else if (status === 402) console.error("Credits exhausted");
    else if (status === 429) console.error("Rate limited — retry later");
    else console.error(`Firecrawl error ${status}:`, err.message);
    return null;
  }
}