Erros

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.

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)"}

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.

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

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.

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.

import timeimport randomimport requestsRETRYABLE_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 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.