Skip to main content
Every Firecrawl error response uses the same JSON shape. Look up the error value (or HTTP status) in the table below to find the cause, remedy, and whether the request is safe to retry.
This catalog covers the errors most agents and clients will encounter. It is non-exhaustive — if you receive an error not listed here, please open an issue so we can document it.

Error response shape

All non-2xx responses return JSON with a top-level success: false and a string error. Some endpoints include additional fields (details, code) when more context is available.

Errors

For 429 responses, Firecrawl includes a Retry-After header (in seconds) when available — wait at least that long before retrying.

Agent

Errors specific to /agent and its status, trace, snapshot, and cancel endpoints. The trace and snapshot endpoints relay their upstream error body unchanged, so those two can answer with a body that omits the success field described above; match on the HTTP status and the error string. A run that hits its maxCredits limit does not return an HTTP error. It finishes as a failed job. Poll the status endpoint and you get status: "failed" with a credit-limit error message, no data, and creditsUsed: 0, since failed runs are not billed. In the trace, the same outcome appears as a run.finished event with outcome: "credit_limit_reached".

Trace error codes

Terminal and error.occurred trace events carry a structured error object whose code is one of five values. Each also carries a retryable boolean, which you should treat the same way as the Retryable column above.

Retry guidance

Treat the Retryable column as authoritative; do not infer from the HTTP status alone. The pattern below uses exponential backoff with jitter and respects Retry-After on 429.

429 responses

429 responses are the most common retryable error. Per-plan rate limits and concurrency limits are documented in Rate Limits. Always honor the Retry-After header when present rather than retrying immediately.