Pular para o conteúdo principal
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.
CampoTipoDescrição
successbooleanSempre false em caso de erro.
errorstringMensagem de erro legível por humanos. Use isto para consultar a linha abaixo.
detailsanyOpcional. Erros de validação estruturados por campo, quando aplicável.

Erros

HTTPerror (mensagem típica)CausaSoluçãoRepetível
400Bad Request / mensagem de validaçãoO corpo da requisição falhou na validação do schema (campos ausentes ou inválidos).Corrija o payload da requisição usando a referência do endpoint. Verifique details para identificar os campos.Não
400Invalid URLO campo url está ausente, malformado ou usa um esquema sem suporte.Informe uma URL absoluta http(s)://.Não
401Unauthorized: Invalid tokenA API key está ausente, malformada ou foi revogada.Envie Authorization: Bearer fc-... com uma chave válida do painel.Não
402Payment Required: Insufficient creditsOs créditos do plano acabaram ou a cobrança não está configurada.Adicione créditos, ative a recarga automática ou faça upgrade do seu plano.Não
403ForbiddenA chave não tem permissão para este endpoint ou recurso.Use uma chave com o escopo necessário ou faça upgrade do plano que libera esse recurso.Não
404Not FoundO ID do job, recurso ou caminho do endpoint não existe.Verifique o ID do recurso e a URL do endpoint.Não
408Request TimeoutA página levou mais tempo para carregar do que o timeout da requisição.Aumente o timeout, simplifique as ações ou use fastMode.Sim, com backoff
409ConflictO recurso está em um estado que impede a operação (por exemplo, já foi excluído).Busque o estado novamente e faça a reconciliação antes de tentar de novo.Não
413Payload Too LargeO corpo da requisição excedeu o tamanho máximo permitido.Reduza o payload (por exemplo, um schema menor ou menos URLs por batch).Não
422Unprocessable Entity / erro no schema de extraçãoO schema é um schema JSON inválido, ou o modelo não conseguiu produzir um resultado compatível.Valide o schema; flexibilize os campos obrigatórios; tente um model diferente.Às vezes
429Rate limit exceededHá requisições demais para o limite por minuto do seu plano.Aplique backoff e tente novamente após os segundos indicados em Retry-After. Consulte Limites de taxa.Sim, com backoff
429Concurrency limit reachedO limite de concorrência do navegador do seu plano foi atingido.Aguarde os jobs em andamento terminarem, reduza a concorrência ou faça upgrade do seu plano.Sim, com backoff
500Internal Server ErrorFalha não tratada no lado do servidor.Tente novamente com backoff exponencial. Se persistir, contate o suporte com o ID da requisição.Sim, com backoff
502Bad GatewayO proxy upstream ou worker retornou uma resposta inválida.Tente novamente com backoff.Sim, com backoff
503Service UnavailableO serviço está temporariamente indisponível para processar a requisição.Tente novamente com backoff.Sim, com backoff
504Gateway TimeoutA requisição excedeu o tempo limite do gateway (normalmente em rastreamentos longos).Use os endpoints assíncronos de rastreamento/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.

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.

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.