> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-docs-remove-capabilities-from-sidebar.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>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.</Note>

<div id="error-response-shape">
  ## Estrutura da resposta de erro
</div>

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 theme={null}
{
  "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. |

<div id="errors">
  ## Erros
</div>

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

<div id="agent">
  ## Agente
</div>

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

<div id="trace-error-codes">
  ### Códigos de erro de rastro
</div>

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

<div id="retry-guidance">
  ## Orientações sobre novas tentativas
</div>

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.

<CodeGroup>
  ```python Python theme={null}
  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 theme={null}
  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 theme={null}
  # 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"
  ```
</CodeGroup>

<div id="429-responses">
  ## Respostas 429
</div>

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.