firecrawl-common-errors

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 <[e-mail]>
tags	["saas","firecrawl","debugging"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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));
    }
  }
}