Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Limites de taxa

Respostas 429 são o erro mais comum que permite nova tentativa. 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.