> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-capy-docs-factual-copy-fixes.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Errores > Todos los códigos de error de la API, qué los causa, cómo resolverlos y si se deben reintentar. 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](https://github.com/firecrawl/firecrawl/issues) 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. ```json theme={null} { "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 habitual) | Causa | Solución | Reintentable | | - | - | - | - | - | | 400 | `Bad Request` / mensaje de validación | El cuerpo de la solicitud no superó la validación del esquema (campos ausentes o no válidos). | Corrige la carga útil de la solicitud utilizando la referencia del punto de conexión. Consulta `details` para ver los campos afectados. | No | | 400 | `Invalid URL` | Falta el campo `url`, su formato no es válido o usa un esquema no compatible. | Envía una URL absoluta `http(s)://`. | No | | 400 | `THIRD_PARTY_DATA_UNSUPPORTED_URL` | La URL pertenece a un sitio cubierto por un provider de datos de terceros, pero el provider solo sirve la página principal de un registro (como una página de perfil), no las subpáginas que cuelgan de ella. La respuesta incluye este valor en `code`. | Haz scraping de la página principal del registro en lugar de una subpágina o un listado que dependa de ella. | No | | 400 | `THIRD_PARTY_DATA_UNSUPPORTED_OPTION` | Esta URL (como un perfil de LinkedIn) solo puede servirla un provider de datos de terceros, y la solicitud establece una opción que el provider no puede respetar: `actions`, `profile`, `minAge`, `zeroDataRetention`, `lockdown`, `redactPII` o un formato no compatible, como `screenshot` o `branding`. `error` indica el nombre de la opción. La respuesta incluye este valor en `code`. | Envía la solicitud sin esa opción. Si la política de tu equipo exige la retención de datos cero, no se pueden servir estas URL. Consulta [URL enrutadas a través de un provider](/es/features/scrape#provider-routed-urls). | No | | 401 | `Unauthorized: Invalid token` | Falta la clave de API, tiene un formato incorrecto o ha sido revocada. | Envía `Authorization: Bearer fc-...` con una clave válida obtenida del [Dashboard](https://www.firecrawl.dev/app/api-keys). | No | | 402 | `Payment Required: Insufficient credits` | Los créditos del plan se han agotado o la facturación no está configurada. | Activa el pago por uso o cambia a un plan superior. | No | | 403 | `Forbidden` | La clave no tiene permisos para acceder a este punto de conexión o función. | Usa una clave con el alcance requerido o cambia a un plan superior que dé acceso a esta función. | No | | 403 | `SCRAPE_PROMPT_INJECTION_DETECTED` | La opción `checkPromptInjection` detectó un intento de inyección de prompts en el contenido de la página extraída, por lo que se abortó el scraping. | Revisa manualmente el contenido de la página. Si se trata de un falso positivo, vuelve a intentarlo sin `checkPromptInjection`. Consulta [Detección de inyección de prompts](/es/features/llm-extract#prompt-injection-detection). | No | | 403 | `THIRD_PARTY_DATA_NOT_ENABLED` | El provider de datos de terceros para esta URL no está habilitado en tu organización, por ejemplo, porque un administrador de la organización lo desactivó. La respuesta incluye este valor en `code`. | Pide a un administrador de la organización que active el provider desde su página de [Alexandria](/es/features/alexandria) o quítalo de tus providers de enriquecimiento. | Una vez habilitado | | 403 | `THIRD_PARTY_DATA_ENRICHMENT_NOT_ENABLED` | La URL corresponde a un perfil o a una página de empresa de LinkedIn, pero el enriquecimiento está desactivado para ese tipo de perfil o ninguno de tus providers de enriquecimiento guardados puede procesarla. La respuesta incluye este valor en `code`, y `error` enlaza a la configuración de enriquecimiento. | Pide a un administrador de la organización que active el enriquecimiento y seleccione los providers en la configuración de enriquecimiento. Consulta [URL enrutadas por provider](/es/features/scrape#provider-routed-urls). | Tras la configuración | | 403 | `We apologize for the inconvenience but we do not support this site...` / `UNSUPPORTED_SITE` | Firecrawl no hace scraping de este sitio y ningún provider de datos de terceros da servicio a esa URL. Algunas respuestas también incluyen `UNSUPPORTED_SITE` en `code`. | Use otra fuente para obtener estos datos. Los clientes Enterprise pueden ponerse en contacto con el equipo de ventas para consultar sobre el sitio. | No | | 403 | `THIRD_PARTY_DATA_TERMS_REQUIRED` | Un provider de [Alexandria](/es/features/alexandria) requiere que tu organización acepte sus términos para poder ejecutar la solicitud. El provider no se ejecutó. La respuesta incluye este valor en `code`, además de `requiresAction.url`. | Envía `requiresAction.url` a un administrador de la organización para que revise y acepte los términos en esa página. Los agentes no deben aceptar los términos por su cuenta. Una vez aceptados, vuelve a enviar la misma solicitud. | Tras aceptar los términos | | 404 | `Not Found` | El ID de trabajo, el recurso o la ruta del punto de conexión no existe. | Verifica el ID del recurso y la URL del punto de conexión. | No | | 404 | `THIRD_PARTY_DATA_NOT_FOUND` | La URL la proporcionan providers de datos de terceros y ninguno tiene un registro de ella. Si hay varios providers de enriquecimiento, se consultaron todos. Los providers sin registro no generan ningún cargo. La respuesta incluye este valor en `code`. | Compruebe que la URL apunte a un perfil o a una página de empresa que exista. Añadir más providers de enriquecimiento puede aumentar la cobertura. | No | | 408 | `Request Timeout` | La página tardó en cargarse más que el `timeout` definido en la solicitud. | Aumenta `timeout`, simplifica las acciones o usa `fastMode`. | Sí, con espera progresiva | | 409 | `Conflict` | El recurso está en un estado que impide la operación (p. ej., ya se ha eliminado). | Vuelva a consultar el estado y resuelva las discrepancias 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., con un esquema más corto o menos URLs por lote). | No | | 422 | `Unprocessable Entity` / error en el esquema de extracción | El esquema no es un JSON Schema válido o el modelo no pudo generar un resultado que se ajuste al esquema. | Valida el esquema; reduce los campos obligatorios; prueba con otro `model`. | A veces | | 429 | `Rate limit exceeded` | Se ha superado el límite de solicitudes por minuto de tu plan. | Reduce la frecuencia de solicitudes y vuelve a intentarlo cuando transcurran los segundos indicados en `Retry-After`. Consulta [Límites de tasa](/es/rate-limits). | Sí, con espera progresiva | | 429 | `Concurrency limit reached` | Se ha alcanzado el límite de navegadores simultáneos de tu plan. | Espera a que terminen los trabajos en curso, reduce la concurrencia o cambia a un plan superior. | Sí, con espera progresiva | | 500 | `Internal Server Error` | Fallo no controlado en el servidor. | Reintenta con espera exponencial. Si el fallo se conserva, ponte en contacto con el soporte e indica el ID de la solicitud. | Sí, con espera progresiva | | 502 | `Bad Gateway` | El proxy o proceso de trabajo upstream devolvió una respuesta no válida. | Reintente aumentando el tiempo de espera entre intentos. | Sí, aumentando el tiempo de espera entre intentos | | 503 | `Service Unavailable` | El servicio no puede procesar la solicitud en este momento. | Reintenta con esperas progresivas. | Sí, con esperas progresivas | | 504 | `Gateway Timeout` | La solicitud superó el tiempo de espera de la puerta de enlace (normalmente en rastreos prolongados). | En su lugar, usa los puntos de conexión asíncronos de rastreo y procesamiento por lotes y consulta el estado. | Sí, con espera progresiva | 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`](/es/features/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 upstream, 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](/es/api-reference/endpoint/agent-trace). | 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](mailto: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](/es/api-reference/endpoint/agent-trace). | 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 `stopReason: "credit_limit_reached"`, un mensaje de error por límite de créditos, sin `data` y con `creditsUsed: 0`, ya que las ejecuciones fallidas no se facturan. La respuesta también puede incluir un resultado parcial `partial` de mejor esfuerzo. Compruebe `stopReason` en lugar de comparar el texto del error, y consulte [Gestión de detenciones por límite de créditos](/es/features/agent#handling-credit-limit-stops) para saber cómo usar un resultado parcial y continuar la ejecución. 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. ```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 # 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 ``` ```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; // Respeta Retry-After cuando esté presente; de lo contrario, usa backoff exponencial con 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} # Bucle simple de shell con backoff exponencial para estados reintentables. 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" ```

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](/es/rate-limits). Respeta siempre la cabecera `Retry-After` cuando esté presente, en lugar de reintentar de inmediato. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.