Erros

Todos os códigos de erro da API, o que os causa, como corrigi-los e se é seguro tentar novamente.

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

Campo	Tipo	Descrição
success	boolean	Sempre false em caso de erro.
error	string	Mensagem de erro legível por humanos. Use isto para consultar a linha abaixo.
details	any	Opcional. Erros de validação estruturados por campo, quando aplicável.

​

Erros

HTTP	error (mensagem típica)	Causa	Solução	Repetível
400	Bad Request / mensagem de validação	O 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
400	Invalid URL	O campo url está ausente, malformado ou usa um esquema sem suporte.	Informe uma URL absoluta http(s)://.	Não
401	Unauthorized: Invalid token	A API key está ausente, malformada ou foi revogada.	Envie Authorization: Bearer fc-... com uma chave válida do painel.	Não
402	Payment Required: Insufficient credits	Os 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
403	Forbidden	A 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
404	Not Found	O ID do job, recurso ou caminho do endpoint não existe.	Verifique o ID do recurso e a URL do endpoint.	Não
408	Request Timeout	A 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
409	Conflict	O 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
413	Payload Too Large	O 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
422	Unprocessable Entity / erro no schema de extração	O 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
429	Rate limit exceeded	Há 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
429	Concurrency limit reached	O 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
500	Internal Server Error	Falha 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
502	Bad Gateway	O proxy upstream ou worker retornou uma resposta inválida.	Tente novamente com backoff.	Sim, com backoff
503	Service Unavailable	O serviço está temporariamente indisponível para processar a requisição.	Tente novamente com backoff.	Sim, com backoff
504	Gateway Timeout	A 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.

Python

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

​

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.