Errores - Firecrawl Docs

Todas las respuestas de error de Firecrawl usan la misma estructura JSON. Busca el valor de error (o el código de estado HTTP) en la tabla siguiente para identificar la causa, cómo corregirlo y si es seguro reintentar la solicitud.

Note

Este catálogo cubre los errores con los que se encontrarán la mayoría de los agentes y clientes. No es exhaustivo: si recibes un error que no aparece aquí, por favor abre un issue para que podamos documentarlo.

Estructura de la respuesta de error#

Todas las respuestas que no son 2xx devuelven JSON con success: false en el nivel superior y un error de tipo cadena. Algunos endpoints incluyen campos adicionales (details, code) cuando hay más contexto disponible.

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

Campo	Tipo	Descripción
`success`	`boolean`	Siempre `false` en caso de error.
`error`	`string`	Mensaje de error comprensible para una persona. Úsalo para consultar la fila siguiente.
`details`	`any`	Opcional. Errores de validación estructurados por campo, cuando corresponda.

Errores#

HTTP	`error` (mensaje típico)	Causa	Solución	Reintentable
400	`Bad Request` / mensaje de validación	El cuerpo de la solicitud no pasó la validación del esquema (faltan campos o son inválidos).	Corrige la carga útil de la solicitud usando la referencia del endpoint. Revisa `details` para identificar los campos.	No
400	`Invalid URL`	Falta el campo `url`, está mal formado o usa un esquema no compatible.	Proporciona una URL absoluta `http(s)://`.	No
401	`Unauthorized: Invalid token`	Falta la clave de API, está mal formada o fue revocada.	Envía `Authorization: Bearer fc-...` con una clave válida desde el dashboard.	No
402	`Payment Required: Insufficient credits`	Los créditos del plan se agotaron o la facturación no está configurada.	Activa el pago por uso o actualiza tu plan.	No
403	`Forbidden`	La clave no tiene permisos para este endpoint o función.	Usa una clave con el alcance requerido o actualiza el plan que habilita esta función.	No
403	`SCRAPE_PROMPT_INJECTION_DETECTED`	El modo JSON con `checkPromptInjection: true` detectó un intento de inyección de prompt en el contenido de la página extraída, por lo que se abortó la extracción.	Inspecciona manualmente el contenido de la página. Si es un falso positivo, reintenta sin `checkPromptInjection`. Consulta Detección de inyección de prompts.	No
404	`Not Found`	El ID de trabajo, el recurso o la ruta del endpoint no existen.	Verifica el ID del recurso y la URL del endpoint.	No
408	`Request Timeout`	La página tardó más que el `timeout` de la solicitud en cargarse.	Aumenta `timeout`, simplifica las acciones o usa `fastMode`.	Sí, con backoff
409	`Conflict`	El recurso está en un estado que impide la operación (p. ej., ya fue eliminado).	Vuelve a consultar el estado y reconcílialo antes de reintentar.	No
413	`Payload Too Large`	El cuerpo de la solicitud superó el tamaño máximo permitido.	Reduce la carga útil (p. ej., un esquema más corto, menos URL por lote).	No
422	`Unprocessable Entity` / error de esquema de extracción	El esquema no es un JSON Schema válido o el modelo no pudo generar un resultado conforme.	Valida el esquema; flexibiliza los campos obligatorios; prueba con otro `model`.	A veces
429	`Rate limit exceeded`	Hay demasiadas solicitudes para el límite por minuto de tu plan.	Espera y reintenta después de los segundos indicados en `Retry-After`. Consulta Límites de tasa.	Sí, con backoff
429	`Concurrency limit reached`	Se alcanzó el límite de navegadores concurrentes de tu plan.	Espera a que terminen los trabajos en curso, reduce la concurrencia o actualiza tu plan.	Sí, con backoff
500	`Internal Server Error`	Error no controlado del lado del servidor.	Reintenta con backoff exponencial. Si persiste, contacta con soporte e indica el ID de la solicitud.	Sí, con backoff
502	`Bad Gateway`	El proxy upstream o el worker devolvió una respuesta no válida.	Reintenta con backoff.	Sí, con backoff
503	`Service Unavailable`	El servicio no puede procesar temporalmente la solicitud.	Reintenta con backoff.	Sí, con backoff
504	`Gateway Timeout`	La solicitud superó el timeout de la puerta de enlace (normalmente en crawls largos).	Usa los endpoints async de crawl/lote y consulta el estado en su lugar.	Sí, con backoff

Para las respuestas 429, Firecrawl incluye una cabecera Retry-After (en segundos) cuando está disponible; espera al menos ese tiempo antes de reintentar.

Agent#

Errores específicos de /agent y de sus endpoints de estado, traza, snapshot y cancelación. Los endpoints de traza y snapshot retransmiten sin cambios el cuerpo de error del servicio ascendente, por lo que pueden responder con un cuerpo que omita el campo success descrito anteriormente; compruebe el código de estado HTTP y la cadena error.

HTTP	`error` (mensaje típico)	Causa	Solución	Reintentable
400	`Invalid job ID format. Job ID must be a valid UUID.`	El segmento de ruta `jobId` no es un UUID.	Pase el `id` devuelto por `POST /v2/agent`.	No
400	`Invalid snapshot ID`	El segmento de ruta `snapshotId` tiene un formato incorrecto.	Use un `snapshotId` de un evento de traza `artifact.updated` evento de traza.	No
400	`Trace is only available for Spark 2 extracts`	El trabajo es anterior a Spark 2, que es el que registra las trazas.	No hay nada que hacer con ese trabajo. Todas las ejecuciones nuevas se realizan en `spark-2` y tienen una traza.	No
400	`Snapshots are only available for Spark 2 extracts`	El trabajo es anterior a Spark 2, que es el que registra los snapshots.	No hay nada que hacer con ese trabajo. Todas las ejecuciones nuevas se realizan en `spark-2` y tienen snapshots.	No
400	`Your team has zero data retention enabled. This is not supported on extract.`	No se pueden atender ejecuciones del agente para un equipo que tenga forzada la retención de datos cero.	Contacte con support@firecrawl.com para habilitar la función para su equipo.	No
404	`Agent job not found`	El ID de trabajo no existe o pertenece a otro equipo.	Compruebe el ID de trabajo y use una clave del equipo que inició la ejecución.	No
404	`Snapshot not found`	Ningún snapshot con ese ID pertenece a este trabajo.	Vuelva a obtener la traza y use un `snapshotId` actual de un evento `artifact.updated` evento de traza.	No
409	`Agent already finished`	Se solicitó la cancelación de una ejecución que ya había alcanzado un estado terminal.	Consulte `GET /v2/agent/{jobId}` para obtener el resultado.	No
409	`Agent is already cancelled`	Se solicitó la cancelación de una ejecución que ya se estaba cancelando.	Consulte `GET /v2/agent/{jobId}`. Una ejecución cancelada informa `failed` con un mensaje de cancelación.	No
500	`Failed to passthrough agent request.`	El servicio del agente rechazó el trabajo al enviarlo.	Reintente con backoff. Si el problema persiste, contacte con soporte e incluya el ID de solicitud.	Sí, con backoff

Una ejecución que alcanza su límite de maxCredits no devuelve un error HTTP. Finaliza como un trabajo fallido. Consulte el endpoint de estado y obtendrá status: "failed" con un mensaje de error por límite de créditos, sin data y con creditsUsed: 0, ya que las ejecuciones fallidas no se facturan. En la traza, el mismo resultado aparece como un evento run.finished con outcome: "credit_limit_reached".

Códigos de error de la traza#

Los eventos de traza terminales y error.occurred contienen un objeto error estructurado cuyo code puede adoptar uno de cinco valores. Cada uno también incluye un booleano retryable, que debes tratar igual que la columna Reintentable anterior.

`code`	Significado y solución
`cancelled`	Cancelaste la ejecución. Inicia una nueva cuando quieras repetir el trabajo.
`credit_limit_reached`	La ejecución alcanzó el límite de `maxCredits`. Aumenta `maxCredits` o acota el prompt para que la ejecución requiera menos trabajo.
`parent_finished`	Un subagente se detuvo porque el agente que lo generó terminó antes. Consulta el evento terminal del agente principal para conocer la causa real.
`refused`	El agente rechazó la tarea. Reformula el prompt o acótalo a URL de las que estés autorizado a recopilar datos.
`internal`	Se produjo un fallo inesperado durante la ejecución. Reintenta la ejecución; si persiste, contacta con soporte e incluye el ID de trabajo.

Guía de reintentos#

Toma la columna Reintentable como referencia definitiva; no lo deduzcas solo a partir del estado HTTP. El patrón siguiente usa backoff exponencial con jitter y respeta Retry-After en respuestas 429.

import timeimport randomimport requestsRETRYABLE_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        # Respeta Retry-After cuando esté presente; de lo contrario, usa backoff exponencial con 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

Respuestas 429#

Las respuestas 429 son el error reintentable más común. Los límites de tasa y de concurrencia por plan se documentan en Límites de tasa. Respeta siempre la cabecera Retry-After cuando esté presente, en lugar de reintentar de inmediato.