firecrawl-common-errors

# 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. ```bash 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](https://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. ```bash 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 ...