> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-docs-remove-capabilities-from-sidebar.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.

<Note>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.</Note>

## 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. | 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](/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.

<CodeGroup>
  ```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"
  ```
</CodeGroup>

## 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.