# 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](https://github.com/firecrawl/firecrawl/issues) 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. ```json { "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 solicitação falhou na validação do schema (campos ausentes ou inválidos). | Corrija o payload da solicitaçã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](https://www.firecrawl.dev/app/api-keys). | Não | | 402 | `Payment Required: Insufficient credits` | Os créditos do plano acabaram ou a cobrança não está configurada. | Ative o pagamento por uso 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 | | 403 | `SCRAPE_PROMPT_INJECTION_DETECTED` | O modo JSON com `checkPromptInjection: true` detectou uma tentativa de injeção de prompt no conteúdo da página extraído, portanto a extração foi interrompida. | Inspecione manualmente o conteúdo da página. Se for um falso positivo, tente novamente sem `checkPromptInjection`. Consulte [Detecção de injeção de prompt](/pt-BR/features/llm-extract#prompt-injection-detection). | 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 solicitaçã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 solicitaçã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á solicitaçõ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](/pt-BR/rate-limits). | 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 solicitaçã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 solicitação. | Tente novamente com backoff. | Sim, com backoff | | 504 | `Gateway Timeout` | A solicitaçã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.
## Agente
Erros específicos de [`/agent`](/pt-BR/features/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. | HTTP | `error` (mensagem típica) | Causa | Solução | Repetível | | ---- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | 400 | `Invalid job ID format. Job ID must be a valid UUID.` | O segmento de caminho `jobId` não é um UUID. | Use o `id` retornado por `POST /v2/agent`. | Não | | 400 | `Invalid snapshot ID` | O segmento de caminho `snapshotId` está malformado. | Use um `snapshotId` de um evento `artifact.updated` do [rastro](/pt-BR/api-reference/endpoint/agent-trace). | Não | | 400 | `Trace is only available for Spark 2 extracts` | O job é anterior ao Spark 2, que registra rastros. | Não há nada a fazer nesse job. Toda nova execução roda no `spark-2` e tem um rastro. | Não | | 400 | `Snapshots are only available for Spark 2 extracts` | O job é anterior ao Spark 2, que registra snapshots. | Não há nada a fazer nesse job. Toda nova execução roda no `spark-2` e tem snapshots. | Não | | 400 | `Your team has zero data retention enabled. This is not supported on extract.` | Não é possível executar o agente para uma equipe com retenção zero de dados obrigatória. | Entre em contato com [support@firecrawl.com](mailto:support@firecrawl.com) para habilitar o recurso para sua equipe. | Não | | 404 | `Agent job not found` | O ID do job não existe ou pertence a outra equipe. | Verifique o ID do job e use uma chave da equipe que iniciou a execução. | Não | | 404 | `Snapshot not found` | Nenhum snapshot com esse ID pertence a este job. | Busque o rastro novamente e use um `snapshotId` atual de um evento `artifact.updated` do [rastro](/pt-BR/api-reference/endpoint/agent-trace). | Não | | 409 | `Agent already finished` | O cancelamento foi solicitado para uma execução que já havia atingido um estado terminal. | Consulte `GET /v2/agent/{jobId}` para obter o resultado. | Não | | 409 | `Agent is already cancelled` | O cancelamento foi solicitado para uma execução que já estava sendo cancelada. | Consulte `GET /v2/agent/{jobId}`. Uma execução cancelada informa `failed` com uma mensagem de cancelamento. | Não | | 500 | `Failed to passthrough agent request.` | O serviço do agente rejeitou o job no envio. | Tente novamente com backoff. Se o problema persistir, entre em contato com o suporte e informe o ID da solicitação. | Sim, com backoff | 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. | `code` | Significado e solução | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cancelled` | Você cancelou a execução. Inicie uma nova quando quiser refazer o trabalho. | | `credit_limit_reached` | A execução atingiu o limite de `maxCredits`. Aumente `maxCredits` ou restrinja o prompt para que a execução exija menos trabalho. | | `parent_finished` | Um subagente foi interrompido porque o agente que o iniciou terminou primeiro. Consulte o evento terminal do agente pai para identificar a causa real. | | `refused` | O agente recusou a tarefa. Reformule o prompt ou restrinja-o a URLs das quais você tem autorização para coletar dados. | | `internal` | Ocorreu uma falha inesperada durante a execução. Tente executar novamente; se persistir, entre em contato com o suporte usando o ID do job. |
## 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 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 ``` ```js Node const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]); async function requestWithRetry(url, init = {}, maxAttempts = 5) { for (let attempt = 0; attempt < maxAttempts; attempt++) { const resp = await fetch(url, init); if (resp.ok || !RETRYABLE_STATUSES.has(resp.status)) return resp; // Respeita Retry-After quando presente; caso contrário, usa backoff exponencial com jitter. const retryAfter = resp.headers.get('Retry-After'); const delayMs = retryAfter ? Number(retryAfter) * 1000 : Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000; await new Promise((r) => setTimeout(r, delayMs)); } } ``` ```bash cURL # Loop simples de shell com backoff exponencial para status que permitem nova tentativa. attempt=0 max=5 until response=$(curl -sS -w "\n%{http_code}" -X POST "https://api.firecrawl.dev/v2/scrape" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com"}'); do status=$(printf '%s' "$response" | tail -n1) case "$status" in 408|429|500|502|503|504) attempt=$((attempt+1)) [ "$attempt" -ge "$max" ] && break sleep $((2 ** attempt)) ;; *) break ;; esac done echo "$response" ```
## 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](/pt-BR/rate-limits). Sempre respeite o cabeçalho `Retry-After`, quando presente, em vez de tentar novamente imediatamente.