Erros

Todos os códigos de erro da API, o que os causa, como corrigi-los e se é seguro tentar novamente.

Todas as respostas de erro do Firecrawl usam o mesmo formato JSON. Consulte o valor de error (ou o status HTTP) na tabela abaixo para identificar a causa, a correção e se a solicitação pode ser repetida com segurança.

Este catálogo cobre os erros que a maioria dos agentes e clientes encontrará. Ele não é exaustivo — se você receber um erro não listado aqui, abra uma issue para que possamos documentá-lo.

​

Estrutura da resposta de erro

Todas as respostas com status diferente de 2xx retornam JSON com success: false no nível superior e uma string error. Alguns endpoints incluem campos adicionais (details, code) quando há mais contexto disponível.

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

Campo	Tipo	Descrição
success	boolean	Sempre false em caso de erro.
error	string	Mensagem de erro legível por humanos. Use isto para consultar a linha abaixo.
details	any	Opcional. Erros de validação estruturados por campo, quando aplicável.

​

Erros

HTTP	error (mensagem típica)	Causa	Solução	Repetível
400	Bad Request / mensagem de validação	O corpo da request não passou na validação do schema (campos ausentes ou inválidos).	Corrija o payload da request com base na referência do endpoint. Consulte details para ver os campos.	Não
400	Invalid URL	O campo url está ausente, malformado ou usa um esquema não compatível.	Envie uma URL absoluta http(s)://.	Não
400	THIRD_PARTY_DATA_UNSUPPORTED_URL	A URL pertence a um site atendido por um provider de dados de terceiros, mas o provider só atende a página do próprio registro (como uma página de perfil), e não as subpáginas dentro dela. A resposta traz esse valor em code.	Faça scraping da página do próprio registro em vez de uma subpágina ou listagem dentro dela.	Não
400	THIRD_PARTY_DATA_UNSUPPORTED_OPTION	Somente um provider de dados de terceiros pode atender a esta URL (como um perfil do LinkedIn), e a request define uma opção que o provider não consegue atender: actions, profile, minAge, zeroDataRetention, lockdown, redactPII ou um formato não suportado, como screenshot ou branding. O campo error informa qual é a opção. A resposta traz esse valor em code.	Envie a request sem essa opção. Se a política da sua equipe exigir retenção zero de dados, essas URLs não poderão ser atendidas. Consulte URLs roteadas por provider.	Não
401	Unauthorized: Invalid token	API key ausente, malformada ou revogada.	Envie Authorization: Bearer fc-... com uma chave válida obtida no painel.	Não
402	Payment Required: Insufficient credits	Os créditos do plano se esgotaram ou a cobrança não está configurada.	Ative o pagamento por uso ou mude para um plano superior.	Não
403	Forbidden	A chave não tem permissão para este endpoint ou recurso.	Use uma chave com o escopo necessário ou mude para um plano superior que dê acesso a este recurso.	Não
403	SCRAPE_PROMPT_INJECTION_DETECTED	A opção checkPromptInjection detectou uma tentativa de prompt injection no conteúdo da página extraída, então o scraping foi interrompido.	Inspecione manualmente o conteúdo da página. Se for um falso positivo, tente novamente sem checkPromptInjection. Consulte Detecção de prompt injection.	Não
403	THIRD_PARTY_DATA_NOT_ENABLED	O provider de dados de terceiros desta URL não está habilitado para sua organização, por exemplo, porque um administrador da organização o desativou. A resposta inclui esse valor em code.	Peça a um administrador da organização que ative o provider na página correspondente do Alexandria ou remova-o dos seus providers de enriquecimento.	Após a ativação
403	THIRD_PARTY_DATA_ENRICHMENT_NOT_ENABLED	A URL é de um perfil ou de uma página de empresa do LinkedIn, mas o enriquecimento está desativado para esse tipo de perfil ou nenhum dos seus providers de enriquecimento salvos consegue atendê-la. A resposta traz esse valor em code, e error inclui um link para a configuração de enriquecimento.	Peça a um administrador da organização que ative o enriquecimento e escolha os providers nas configurações de enriquecimento. Consulte URLs roteadas por provider.	Após a configuração
403	We apologize for the inconvenience but we do not support this site... / UNSUPPORTED_SITE	O Firecrawl não faz scraping deste site, e nenhum provider de dados de terceiros atende essa URL. Algumas respostas também incluem UNSUPPORTED_SITE em code.	Use outra fonte para obter esses dados. Clientes Enterprise podem entrar em contato com a equipe de vendas para tratar do suporte ao site.	Não
403	THIRD_PARTY_DATA_TERMS_REQUIRED	Um provider do Alexandria exige que sua organização aceite os termos de uso dele antes que a request possa ser executada. O provider não foi executado. A resposta traz esse valor em code e inclui requiresAction.url.	Envie requiresAction.url a um administrador da organização, que deverá revisar e aceitar os termos nesse endereço. Agentes não devem aceitar os termos por conta própria. Após a aceitação, envie a mesma request novamente.	Após o aceite dos termos
404	Not Found	O ID do job, o recurso ou o caminho do endpoint não existe.	Verifique o ID do recurso e a URL do endpoint.	Não
404	THIRD_PARTY_DATA_NOT_FOUND	A URL é atendida por providers de dados de terceiros, e nenhum deles tem registro dela. Quando há vários providers de enriquecimento, todos são consultados. Providers sem registro não geram cobrança. A resposta traz esse valor em code.	Verifique se a URL aponta para um perfil ou uma página de empresa que exista. Adicionar mais providers de enriquecimento pode aumentar a cobertura.	Não
408	Request Timeout	A página demorou mais para carregar do que o timeout definido na request.	Aumente o timeout, simplifique as ações ou use o fastMode.	Sim, com espera progressiva
409	Conflict	O recurso está em um estado que impede a operação (por exemplo, já foi excluído).	Consulte novamente o estado e resolva as inconsistências antes de fazer uma nova tentativa.	Não
413	Payload Too Large	O corpo do request excedeu o tamanho máximo permitido.	Reduza o payload (por exemplo, um schema menor ou menos URLs por lote).	Não
422	Unprocessable Entity / erro no schema de extração	O schema não é um schema JSON válido ou o modelo não conseguiu gerar um resultado que siga o schema.	Valide o schema; torne os campos obrigatórios menos restritivos; tente outro model.	Às vezes
429	Rate limit exceeded	O número de requests excede o limite por minuto do seu plano.	Aguarde e tente novamente após Retry-After segundos. Consulte Limites de taxa.	Sim, com espera progressiva
429	Concurrency limit reached	O limite de navegadores simultâneos do seu plano foi atingido.	Aguarde a conclusão dos jobs em andamento, reduza a concorrência ou mude para um plano superior.	Sim, com espera progressiva
500	Internal Server Error	Falha não tratada no servidor.	Tente novamente com espera exponencial. Se a falha persistir, entre em contato com o suporte e informe o ID da request.	Sim, com espera progressiva
502	Bad Gateway	O proxy ou worker upstream retornou uma resposta inválida.	Tente novamente com espera progressiva.	Sim, com espera progressiva
503	Service Unavailable	O serviço está temporariamente impossibilitado de processar o request.	Tente novamente com espera progressiva.	Sim, com espera progressiva
504	Gateway Timeout	O request excedeu o tempo limite do gateway (geralmente em rastreamentos longos).	Em vez disso, use os endpoints assíncronos crawl/batch e consulte o status.	Sim, com backoff

Para respostas 429, o Firecrawl inclui um cabeçalho Retry-After (em segundos) quando disponível — aguarde pelo menos esse tempo antes de tentar novamente.

​

Agente

Erros específicos de /agent e de seus endpoints de status, rastro, snapshot e cancelamento. Os endpoints de rastro e snapshot retransmitem o corpo de erro upstream sem alterações; por isso, esses dois podem responder com um corpo que omite o campo success descrito acima. Use o status HTTP e a string error para a correspondência.

HTTP	error (mensagem típica)	Causa	Solução	Repetível
400	Invalid job ID format. Job ID must be a valid UUID.	O segmento de caminho jobId não é um UUID.	Use o id retornado por POST /v2/agent.	Não
400	Invalid snapshot ID	O segmento de caminho snapshotId está malformado.	Use um snapshotId de um evento artifact.updated do rastro.	Não
400	Trace is only available for Spark 2 extracts	O job é anterior ao Spark 2, que registra rastros.	Não há nada a fazer nesse job. Toda nova execução roda no spark-2 e tem um rastro.	Não
400	Snapshots are only available for Spark 2 extracts	O job é anterior ao Spark 2, que registra snapshots.	Não há nada a fazer nesse job. Toda nova execução roda no spark-2 e tem snapshots.	Não
400	Your team has zero data retention enabled. This is not supported on extract.	Não é possível executar o agente para uma equipe com retenção zero de dados obrigatória.	Entre em contato com [e-mail] para habilitar o recurso para sua equipe.	Não
404	Agent job not found	O ID do job não existe ou pertence a outra equipe.	Verifique o ID do job e use uma chave da equipe que iniciou a execução.	Não
404	Snapshot not found	Nenhum snapshot com esse ID pertence a este job.	Busque o rastro novamente e use um snapshotId atual de um evento artifact.updated do rastro.	Não
409	Agent already finished	O cancelamento foi solicitado para uma execução que já havia atingido um estado terminal.	Consulte GET /v2/agent/{jobId} para obter o resultado.	Não
409	Agent is already cancelled	O cancelamento foi solicitado para uma execução que já estava sendo cancelada.	Consulte GET /v2/agent/{jobId}. Uma execução cancelada informa failed com uma mensagem de cancelamento.	Não
500	Failed to passthrough agent request.	O serviço do agente rejeitou o job no envio.	Tente novamente com backoff. Se o problema persistir, entre em contato com o suporte e informe o ID da solicitação.	Sim, com backoff

Uma execução que atinge o limite de maxCredits não retorna um erro HTTP. Ela termina como um job com falha. Consulte o endpoint de status para receber status: "failed" com stopReason: "credit_limit_reached", uma mensagem de erro de limite de crédito, sem data e com creditsUsed: 0, pois execuções com falha não são cobradas. A resposta também pode incluir um partial, gerado com base no melhor esforço. Verifique stopReason em vez de comparar o texto do erro e consulte Lidando com interrupções por limite de crédito para saber como usar um resultado parcial e dar continuidade à execução. No rastro, o mesmo resultado aparece como um evento run.finished com outcome: "credit_limit_reached".

​

Códigos de erro de rastro

Eventos de rastro terminal e error.occurred contêm um objeto error estruturado cujo code é um dentre cinco valores. Cada um também contém um booleano retryable, que deve ser tratado da mesma forma que a coluna Repetível acima.

code	Significado e solução
cancelled	Você cancelou a execução. Inicie uma nova quando quiser refazer o trabalho.
credit_limit_reached	A execução atingiu o limite de maxCredits. Aumente maxCredits ou restrinja o prompt para que a execução exija menos trabalho.
parent_finished	Um subagente foi interrompido porque o agente que o iniciou terminou primeiro. Consulte o evento terminal do agente pai para identificar a causa real.
refused	O agente recusou a tarefa. Reformule o prompt ou restrinja-o a URLs das quais você tem autorização para coletar dados.
internal	Ocorreu uma falha inesperada durante a execução. Tente executar novamente; se persistir, entre em contato com o suporte usando o ID do job.

​

Orientações sobre novas tentativas

Considere a coluna Repetível como a referência principal; não deduza isso apenas pelo status HTTP. O padrão abaixo usa backoff exponencial com jitter e respeita Retry-After em respostas 429.

Python

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
        # Respeita Retry-After quando presente; caso contrário, usa backoff exponencial com 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

​

Respostas 429

Respostas 429 são o erro repetível mais comum. Os limites de taxa por plano e os limites de concorrência estão documentados em Limites de taxa. Sempre respeite o cabeçalho Retry-After, quando presente, em vez de tentar novamente imediatamente.