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
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
/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
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
Retry-After em respostas 429.
Respostas 429
Retry-After, quando presente, em vez de tentar novamente imediatamente.
