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

Erros

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

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.