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-levelsuccess: 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 anderror.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 respectsRetry-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 theRetry-After header when present rather than retrying immediately.
