> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-docs-agent-transparency-gaps.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://github.com/firecrawl/firecrawl/issues) 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.
```json theme={null}
{
"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 |
| 401 | `Unauthorized: Invalid token` | API key is missing, malformed, or revoked. | Send `Authorization: Bearer fc-...` with a valid key from the [dashboard](https://www.firecrawl.dev/app/api-keys). | No |
| 402 | `Payment Required: Insufficient credits` | Plan credits are exhausted or billing is not configured. | Top up credits, enable auto-recharge, 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](/features/llm-extract#prompt-injection-detection). | No |
| 404 | `Not Found` | The job ID, resource, or endpoint path does not exist. | Verify the resource ID and endpoint URL. | 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](/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`](/features/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](/api-reference/endpoint/agent-trace). | 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 [support@firecrawl.com](mailto:support@firecrawl.com) 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](/api-reference/endpoint/agent-trace). | 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 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.
| `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 Python theme={null}
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
```
```js Node theme={null}
const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
async function requestWithRetry(url, init = {}, maxAttempts = 5) {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const resp = await fetch(url, init);
if (resp.ok || !RETRYABLE_STATUSES.has(resp.status)) return resp;
// Honor Retry-After when present, otherwise exponential backoff with jitter.
const retryAfter = resp.headers.get('Retry-After');
const delayMs = retryAfter
? Number(retryAfter) * 1000
: Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000;
await new Promise((r) => setTimeout(r, delayMs));
}
}
```
```bash cURL theme={null}
# Simple shell loop with exponential backoff for retryable statuses.
attempt=0
max=5
until response=$(curl -sS -w "\n%{http_code}" -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'); do
status=$(printf '%s' "$response" | tail -n1)
case "$status" in
408|429|500|502|503|504)
attempt=$((attempt+1))
[ "$attempt" -ge "$max" ] && break
sleep $((2 ** attempt))
;;
*) break ;;
esac
done
echo "$response"
```
## 429 responses
429 responses are the most common retryable error. Per-plan rate limits and concurrency limits are documented in [Rate Limits](/rate-limits). Always honor the `Retry-After` header when present rather than retrying immediately.