Errors

Every API error code, what causes it, how to remedy it, and whether to retry.

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.

{
  "success": false,
  "error": "Unauthorized: Invalid token",
  "details": "Optional structured details (only present on some errors)"
}

Field	Type	Description
success	boolean	Always false on errors.
error	string	Human-readable error message. Use this to look up the row below.
details	any	Optional. Structured per-field validation errors when applicable.

Errors

HTTP	error (typical message)	Cause	Remedy	Retryable
400	Bad Request / validation message	Request body failed schema validation (missing or invalid fields).	Fix the request payload using the endpoint reference. Check details for fields.	No
400	Invalid URL	The url field is missing, malformed, or uses an unsupported scheme.	Pass an absolute http(s):// URL.	No
400	THIRD_PARTY_DATA_UNSUPPORTED_URL	The URL belongs to a site that a third-party data provider serves, but the provider only serves a record’s own page (such as a profile page), not the sub-pages under it. The response has this value in code.	Scrape the record’s own page instead of a sub-page or listing under it.	No
400	THIRD_PARTY_DATA_UNSUPPORTED_OPTION	Only a third-party data provider may serve this URL (such as a LinkedIn profile), and the request sets an option the provider can’t honor: actions, profile, minAge, zeroDataRetention, lockdown, redactPII, or an unsupported format such as screenshot or branding. error names the option. The response has this value in code.	Send the request without that option. If your team’s policy enforces zero data retention, these URLs can’t be served. See Provider-routed URLs.	No
401	Unauthorized: Invalid token	API key is missing, malformed, or revoked.	Send Authorization: Bearer fc-... with a valid key from the dashboard.	No
402	Payment Required: Insufficient credits	Plan credits are exhausted or billing is not configured.	Turn on pay-as-you-go, or upgrade your plan.	No
403	Forbidden	Key lacks permission for this endpoint or feature.	Use a key with the required scope, or upgrade the plan that gates this feature.	No
403	SCRAPE_PROMPT_INJECTION_DETECTED	JSON mode with checkPromptInjection: true detected a prompt injection attempt in the scraped page content, so extraction was aborted.	Inspect the page content manually. If it is a false positive, retry without checkPromptInjection. See Prompt injection detection.	No
403	THIRD_PARTY_DATA_NOT_ENABLED	The third-party data provider for this URL is not enabled for your organization, for example because an org admin turned it off. The response has this value in code.	Ask an org admin to turn the provider on from its Alexandria page, or remove it from your enrichment providers.	After it is enabled
403	THIRD_PARTY_DATA_ENRICHMENT_NOT_ENABLED	The URL is a LinkedIn profile or company page, but enrichment is off for that kind of profile, or none of your saved enrichment providers can serve it. The response has this value in code, and error links to the enrichment settings.	Ask an org admin to turn on enrichment and choose providers in the enrichment settings. See Provider-routed URLs.	After setup
403	We apologize for the inconvenience but we do not support this site... / UNSUPPORTED_SITE	Firecrawl does not scrape this site, and no third-party data provider serves the URL. Some responses also have UNSUPPORTED_SITE in code.	Use a different source for this data. Enterprise customers can contact sales about the site.	No
403	THIRD_PARTY_DATA_TERMS_REQUIRED	An Alexandria provider needs your organization to accept its terms before the request can run. The provider did not run. The response has this value in code, and includes requiresAction.url.	Send requiresAction.url to an org admin, who reviews and accepts the terms there. Agents must not accept terms on their own. After acceptance, send the same request again.	After acceptance
404	Not Found	The job ID, resource, or endpoint path does not exist.	Verify the resource ID and endpoint URL.	No
404	THIRD_PARTY_DATA_NOT_FOUND	The URL is served by third-party data providers, and none of them has a record for it. With several enrichment providers, every one was tried. A provider with no record charges nothing. The response has this value in code.	Check the URL points to an existing profile or company page. Adding more enrichment providers can raise coverage.	No
408	Request Timeout	The page took longer than the request timeout to load.	Increase timeout, simplify actions, or use fastMode.	Yes, with backoff
409	Conflict	Resource is in a state that prevents the operation (e.g. already deleted).	Re-fetch state and reconcile before retrying.	No
413	Payload Too Large	Request body exceeded the maximum allowed size.	Reduce the payload (e.g. shorter schema, fewer URLs per batch).	No
422	Unprocessable Entity / extraction schema error	Schema is invalid JSON Schema, or the model could not produce a conforming result.	Validate the schema; loosen required fields; try a different model.	Sometimes
429	Rate limit exceeded	Too many requests for your plan’s per-minute limit.	Back off and retry after Retry-After seconds. See Rate Limits.	Yes, with backoff
429	Concurrency limit reached	Concurrent browser limit for your plan reached.	Wait for in-flight jobs to finish, lower concurrency, or upgrade your plan.	Yes, with backoff
500	Internal Server Error	Unhandled server-side failure.	Retry with exponential backoff. If it persists, contact support with the request ID.	Yes, with backoff
502	Bad Gateway	Upstream proxy or worker returned an invalid response.	Retry with backoff.	Yes, with backoff
503	Service Unavailable	Service temporarily unable to handle the request.	Retry with backoff.	Yes, with backoff
504	Gateway Timeout	Request exceeded the gateway’s timeout (typically long crawls).	Use the async crawl/batch endpoints and poll status instead.	Yes, with backoff

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.

HTTP	error (typical message)	Cause	Remedy	Retryable
400	Invalid job ID format. Job ID must be a valid UUID.	The jobId path segment is not a UUID.	Pass the id returned by POST /v2/agent.	No
400	Invalid snapshot ID	The snapshotId path segment is malformed.	Use a snapshotId taken from an artifact.updated trace event.	No
400	Trace is only available for Spark 2 extracts	The job predates Spark 2, which is what records traces.	Nothing to do for that job. Every new run executes on spark-2 and has a trace.	No
400	Snapshots are only available for Spark 2 extracts	The job predates Spark 2, which is what records snapshots.	Nothing to do for that job. Every new run executes on spark-2 and has snapshots.	No
400	Your team has zero data retention enabled. This is not supported on extract.	Agent runs cannot be served for a team with zero data retention forced on.	Contact [e-mail] to unblock the feature for your team.	No
404	Agent job not found	The job ID does not exist, or belongs to another team.	Check the job ID, and use a key from the team that started the run.	No
404	Snapshot not found	No snapshot with that ID belongs to this job.	Re-fetch the trace and use a current snapshotId from an artifact.updated trace event.	No
409	Agent already finished	Cancel was called on a run that had already reached a terminal state.	Poll GET /v2/agent/{jobId} for the outcome instead.	No
409	Agent is already cancelled	Cancel was called on a run that was already cancelling.	Poll GET /v2/agent/{jobId}. A cancelled run reports failed with a cancellation message.	No
500	Failed to passthrough agent request.	The agent service rejected the job at submission.	Retry with backoff. If it persists, contact support with the request ID.	Yes, with backoff

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 stopReason: "credit_limit_reached", a credit-limit error message, no data, and creditsUsed: 0, since failed runs are not billed. The response may also include a best-effort partial. Check stopReason rather than matching the error text, and see Handling credit-limit stops for how to use a partial and continue the run. 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.

code	Meaning and remedy
cancelled	You cancelled the run. Start a new one when you want the work redone.
credit_limit_reached	The run hit its maxCredits ceiling. Raise maxCredits, or narrow the prompt so the run needs less work.
parent_finished	A subagent stopped because the agent that spawned it finished first. Read the parent agent’s own terminal event for the real cause.
refused	The agent declined the task. Rephrase the prompt, or scope it to URLs you’re authorized to collect from.
internal	An unexpected failure inside the run. Retry the run; if it persists, contact support with the job ID.

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.

Python

import time
import random
import requests

RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}

def request_with_retry(method, url, headers=None, json=None, max_attempts=5):
    for attempt in range(max_attempts):
        resp = requests.request(method, url, headers=headers, json=json)
        if resp.status_code < 400 or resp.status_code not in RETRYABLE_STATUSES:
            return resp
        # Honor Retry-After when present, otherwise exponential backoff with jitter.
        retry_after = resp.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else min(2 ** attempt, 30) + random.random()
        time.sleep(delay)
    return resp

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.