Skip to content
Skills Library
Programming · Analysis

firecrawl-common-errors

/firecrawl-common-errors

Analyze and resolve current Firecrawl v2 validation, authentication, credit, policy, rate, concurrency, timeout, and server errors. Use when an API or SDK call fails. Trigger with "Firecrawl error", "Firecrawl 429", "Firecrawl 402", or "Firecrawl forbidden".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Analyze and resolve current Firecrawl v2 validation, authentication, credit, policy, rate, concurrency, timeout, and server errors. Use when an API or SDK call fails. Trigger with "Firecrawl error", "Firecrawl 429", "Firecrawl 402", or "Firecrawl forbidden".

Triggers from the description

Firecrawl errorFirecrawl 429Firecrawl 402Firecrawl forbidden

Arguments

/firecrawl-common-errors <status-or-error> [request-id]
Original author description

Analyze and resolve current Firecrawl v2 validation, authentication, credit, policy, rate, concurrency, timeout, and server errors. Use when an API or SDK call fails. Trigger with "Firecrawl error", "Firecrawl 429", "Firecrawl 402", or "Firecrawl forbidden".

How it works

  1. Overview
  2. Prerequisites
  3. Current Contract
  4. Authentication
  5. Instructions
  6. Tool Discipline
  7. Approval Boundaries
  8. Output
  9. Error Handling
  10. Examples
Original SKILL.md headings · 65 lines, 538 words
SKILL.md preview
---
name: firecrawl-common-errors
description: >-
  Analyze and resolve current Firecrawl v2 validation, authentication, credit, policy, rate, concurrency, timeout, and server errors. Use when an API or SDK call fails. Trigger with "Firecrawl error", "Firecrawl 429", "Firecrawl 402", or "Firecrawl forbidden".
allowed-tools: Read,Glob,Grep,Write,Edit
argument-hint: "<status-or-error> [request-id]"
version: 1.12.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags: [saas, firecrawl, errors, troubleshooting]
model: inherit
effort: high
compatibility: "Designed for Claude Code; Firecrawl Cloud work requires network access"
---
# Firecrawl Error Triage

## Overview

Translate an error into a safe next action using Firecrawl's published error catalog. Do not retry every non-success response and do not confuse a returned document with an origin error status for an API failure.

## Prerequisites

- The target repository or integration path and the requested operator outcome.
- The source authorization, data classification, and environment policy.
- Current Firecrawl documentation, credentials only when needed, and an owner for approvals.

## Current Contract

Non-2xx REST responses normally contain success false and an error string, sometimes details or code. The current retryable status set is 408, 429, 500, 502, 503, and 504; 422 is conditional. Authentication, insufficient-credit, restriction, and request-shape failures require correction rather than blind retry.

## Authentication

For authenticated Cloud operations, inject FIRECRAWL_API_KEY from an approved
secret manager. REST requests use Authorization: Bearer with the key. Never print,
commit, transmit, or place a key in a URL. Keyless access is suitable only where
the current documentation explicitly allows it and the workload accepts its
limits; production workflows should make identity and team ownership explicit.

## Instructions

1. Capture the HTTP status, error string, optional code/details, request or job ID, operation, timestamp, SDK version, and a redacted request shape.
2. Check metadata.statusCode on returned documents. A captured 403 or 404 page consumes a result path and should not be handled like an API transport error.
3. For 400 or 422, validate the request against the current endpoint schema and simplify JSON extraction requirements before retrying.
4. For 401, verify secret injection and key selection without printing the key. For 402, stop work and route the credit or billing decision to the owner.
5. For 403, inspect plan entitlement, team ownership, endpoint/format key restrictions, IP restrictions, or policy controls; never bypass them with another uncontrolled key.
6. For 429, distinguish rate from concurrency pressure, honor Retry-After when available, reduce producers, and use queue status evidence.
7. For retryable timeouts or server failures, use bounded exponential backoff with jitter, then escalate with redacted IDs and timestamps.

## Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, tests, and evidence. Use
Write/Edit only for approved implementation or documentation changes. Do not call
Firecrawl, rotate keys, change account settings, scrape a target, or deploy merely
because this skill was invoked.

## Approval Boundaries

Require approval before rotating credentials, enabling pay-as-you-go, upgrading a plan, relaxing a key/IP restriction, increasing concurrency, or sharing target details with support.

## Output

Return the exact classification, retryability decision, safe remediation, attempts used, affected scope, redacted evidence, escalation owner, and prevention test.

## Error Handling

- Unknown error: preserve its exact status and error string and compare with current docs or support.
- Error body cannot be parsed: fall back to status, headers, request ID, and bounded transport diagnostics.
- Retry budget is exhausted: stop and escalate; do not create an unbounded retry loop.

## Examples

- "Firecrawl returns 429" distinguishes team rate limits from browser concurrency and queue saturation.
- "A scrape succeeded with statusCode 403" treats it as captured origin content, not a successful source page.

## Resources

Read [official Firecrawl evidence](references/official-docs.md) before relying on
an endpoint, SDK method, plan limit, price, retention option, or self-hosted release.
Files in this package (2)
  • SKILL.md 4 KB
  • references/official-docs.md 2 KB

Versions

RepositoryScoreLicence
This page · jeremylongshore/tons-of-skills-marketplace100MIT
HelixDevelopment/agent100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 179297f7c203 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100firecrawl-install-auth
    Install and configure FireCrawl SDK/CLI authentication. Use when setting up a new FireCrawl integration, configuring API keys, or initializing FireCrawl in your project. Trigger with phrases like "install firecrawl", "setup firecrawl", "firecrawl auth", "configure firecrawl API key".
  • 100firecrawl-rate-limits
    Implement FireCrawl rate limiting, backoff, and idempotency patterns. Use when handling rate limit errors, implementing retry logic, or optimizing API request throughput for FireCrawl. Trigger with phrases like "firecrawl rate limit", "firecrawl throttling", "firecrawl 429",…
  • 100firecrawl-install-auth
    Install the current Firecrawl Node or Python SDK, configure Cloud authentication, and verify package provenance and secret injection. Use when bootstrapping or repairing client setup. Trigger with "install Firecrawl", "configure FIRECRAWL_API_KEY", or "Firecrawl authentication".
  • 100firecrawl-upgrade-migration
    Upgrade a Firecrawl client from legacy v0/v1 routes and methods to the current v2 SDK and API with contract, parity, and rollback evidence. Use when modernizing an existing Firecrawl integration. Trigger with "upgrade Firecrawl", "migrate Firecrawl v1 to v2", or "replace scrapeUrl".
  • 90firecrawl-sdk
    Integrate Firecrawl into product code: SDK setup and FIRECRAWL_API_KEY onboarding, /scrape, /search and /interact endpoints. Use when an application (not the agent itself) calls Firecrawl.
  • 100firecrawl-qa
    Test a live website with Firecrawl browser and write up what's broken: links, forms, mobile layout, performance and console errors. Use for pre-launch checks, bug hunts or confirming a deployed site works.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.