Skip to main content
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.
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.

Errores

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

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.

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.