# Erros do Servidor MCP

> URL: https://foura.ai/pt/docs/mcp/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Como tratar erros retornados pelo servidor [foura-mcp](https://foura.ai/docs/mcp/server).

Toda resposta de erro de qualquer uma das quatro ferramentas (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) é estruturada. Agentes de LLM podem ler o campo `code` para lógica de repetição sem analisar texto livre.

## Formato do envelope

Todo erro (`isError: true`) contém um bloco `structuredContent`. Campos mínimos em cada erro:

```json
{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}
```

Em erros de upstream com status HTTP, `status` também está presente. Quando a franquia compartilhada da plataforma recusa uma chamada, o envelope adiciona `retryAfter`, `current.{concurrency, rpm}` e `limits.{maxConcurrency, maxRpm}`, com o mesmo formato dos [erros da REST API](https://foura.ai/docs/api/errors) subjacentes.

Quando um dos limites do seu próprio plano recusa uma chamada, o código É esse limite: `plan_limit_` seguido por `credits`, `bandwidth`, `rate`, `concurrency`, `browser_daily`, `premium` ou `feature`. `retryAfter` informa o tempo de espera quando aguardar resolve o bloqueio, e fica ausente em limites que a espera não pode resolver, como um recurso não incluído no plano. `plan_limit_browser_daily` também não traz `retryAfter`: ele é liberado à meia-noite UTC. `plan_limit_credits` e `plan_limit_bandwidth` limitam `retryAfter` a 24 horas e adicionam `resets_at`, o final exato do período de faturamento, portanto leia `resets_at` antes de agendar uma nova tentativa.

No `foura_auto`, um limite de plano atingido dentro da sua hierarquia retorna como `rate_limited` ou `forbidden`, com o código do plano em `reason`.

## Valores estáveis de `code`

| Código | HTTP | Significado | Seguro repetir? |
|---|---|---|---|
| `ssrf_blocked` | n/a | O destino é um endereço privado ou reservado (RFC 5735, RFC 6598, IPv6 reservado), a URL não é http(s), ou o nome do host não foi resolvido | Não, verifique a URL. Uma resolução que falhou brevemente pode ser repetida |
| `upstream_non_json` | varia | O upstream retornou um corpo que não era um JSON válido | Talvez, investigue |
| `output_validation_failed` | n/a | O `outputSchema` do servidor MCP rejeitou a resposta do upstream, ou a ferramenta não conseguiu concluir a chamada (nenhuma chave de API configurada, API inacessível) | Talvez: verifique a configuração e depois reporte |
| `bad_request` | 400 | Formato de entrada rejeitado pela API do FourA, a URL de destino aponta para a própria API do FourA em vez de uma página (apenas `/inspect` pode ser obtido lá), a URL contém um espaço não codificado (codifique-o como `%20`), ou `proxy` especifica uma saída que a chamada não pode usar: uma saída premium após o término do tráfego premium responde `Managed exit: this proxy id cannot be pinned to a request`. Nada é buscado ou cobrado | Não, corrija os argumentos |
| `auth_failed` | 401 | A chave de API do FourA está ausente, inválida ou desativada; isso não se refere às credenciais do site de destino | Não, corrija a chave do FourA |
| `forbidden` | 403 | O destino respondeu 403 e o seu `validate` rejeitou a resposta (verificação do site, restrição por país) | Não, ou mude para `foura_proxy` |
| `not_found` | 404 | A URL ou endpoint de destino não existe | Não |
| `rate_limited` | 429 | Limite compartilhado por minuto da plataforma, ou um 429 do destino que o seu `validate` rejeitou. No `foura_auto` também pode ser o limite de créditos, tráfego ou rate limit do seu plano (consulte `reason`) | Sim, aguarde `retryAfter` quando presente, caso contrário use backoff |
| `at_capacity` | 503 | Limite de concorrência atingido (`current.concurrency` > `limits.maxConcurrency`), ou o serviço está temporariamente desativado para manutenção (`error` exibe `Service disabled`, `retryAfter` é 60) | Sim, aguarde `retryAfter` segundos |
| `service_disabled` | 503 | Reservado. Um serviço desativado para manutenção retorna atualmente `at_capacity`, e uma ferramenta que o seu plano não inclui retorna `plan_limit_feature` | Entre em contato com o suporte |
| `service_unavailable` | 503 | 503 genérico do upstream | Sim, backoff curto |
| `upstream_error` | 500+ ou 0 | O destino respondeu com erro do servidor, ou no `foura_proxy`, `foura_browser` e `foura_auto` nunca responderam | Sim, backoff exponencial |
| `upstream_client_error` | 4xx | Outro 4xx não coberto acima | Geralmente não |
| `upstream_unknown` | outro | A requisição foi executada mas não produziu uma resposta aceita: no `foura_single` o destino nunca respondeu (timeout, conexão recusada), e em qualquer ferramenta o seu `validate` rejeitou uma resposta 2xx ou 3xx. Leia `status` e `error` | Investigue |
| `no_eligible_proxy` | n/a | Nenhum proxy corresponde à allowlist restrita de `exitCountries`; `details.exitCountries` contém o escopo normalizado | Tente novamente mais tarde; altere o escopo apenas explicitamente |
| `plan_limit_credits` | 429 | Os créditos mensais do seu plano foram esgotados | Sim, após `retryAfter`, ou mude de plano |
| `plan_limit_bandwidth` | 429 | A franquia de tráfego do seu plano foi esgotada para este período de faturamento | Sim, após `retryAfter`, ou mude de plano |
| `plan_limit_rate` | 429 | Requisições por minuto do seu plano para esse endpoint | Sim, após `retryAfter` |
| `plan_limit_concurrency` | 429 | Requisições simultâneas do seu plano para esse endpoint | Sim, após `retryAfter` |
| `plan_limit_browser_daily` | 429 | A cota diária de Browser do seu plano foi esgotada | Sim, amanhã, ou use `foura_single` / `foura_proxy` |
| `plan_limit_premium` | 403 | Você enviou `exitClass: "premium"` em um plano que não inclui saídas premium | Não, remova o parâmetro ou mude de plano |
| `plan_limit_feature` | 403 | O plano não dá acesso a esse endpoint ou recurso | Não, mude de plano |

## Erros de nível HTTP do servidor MCP

Algumas falhas ocorrem na camada de transporte do MCP, antes que qualquer ferramenta seja chamada. Elas retornam erros brutos de JSON-RPC (sem `structuredContent`):

| HTTP | Quando | O que você vê |
|---|---|---|
| 400 | Header `MCP-Protocol-Version` não suportado | `Unsupported MCP-Protocol-Version: <value>. Supported (from @modelcontextprotocol/sdk): 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07. Upgrade foura-mcp's SDK pin to extend.` |
| 401 | Chamada de ferramenta ou leitura de recurso sem chave de API. Listar ferramentas e prompts funciona sem ela | Erro de JSON-RPC + `WWW-Authenticate: Bearer realm="foura-mcp"` |
| 403 | Header `Origin` ou `Host` não permitido (defesa contra DNS-rebinding, CVE-2025-66414) | `Origin <value> is not in the allowlist` ou `Host <value> is not in the allowlist` |
| 405 | `GET` ou `DELETE` em `/mcp` (modo stateless) | `Method not allowed in stateless mode. Use POST /mcp.` |
| 413 | Corpo da request > 256 KB | Padrão 413 do Express |

As allowlists para 403 são configuráveis via variáveis de ambiente para quem usa self-hosting com `FOURA_MCP_ALLOWED_HOSTS` e `FOURA_MCP_ALLOWED_ORIGINS`.

## Perfis de navegador recusados

Um perfil de navegador que o catálogo não pode fornecer, ou um perfil enviado com `unblocker` definido como `false`, retorna como uma falha upstream com o motivo em `error`, e a request nunca sai da FourA. Para uma combinação inexistente de `browser`, `os` e `version`, a mensagem informa o que está disponível; portanto, tente novamente com uma das combinações listadas em vez de repetir a mesma. Um id `profile` desconhecido recebe `unknown profile` sem lista: consulte o id em [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles).

Trata-se de recusas, não de indisponibilidades: repetir a request idêntica não terá sucesso, e nenhum outro navegador foi usado em seu lugar.

## Estratégia de retry

Cinco categorias:

- **O seu próprio plano recusou, não o destino**: qualquer código `plan_limit_*`. `plan_limit_credits` e `plan_limit_bandwidth` contabilizam a conta inteira, portanto o mesmo trabalho por meio de outra ferramenta também será recusado. `plan_limit_rate`, `plan_limit_concurrency`, `plan_limit_browser_daily` e `plan_limit_feature` aplicam-se a um endpoint, portanto outra ferramenta ainda pode ser executada se puder realizar o trabalho. Aguarde o `retryAfter` quando houver um; caso contrário, o plano precisa mudar. `plan_limit_premium` é o que você mesmo pode resolver, removendo `exitClass`.
- **Aguarde e tente novamente**: `rate_limited`, `at_capacity`, `service_unavailable`, `upstream_error`. Respeite `retryAfter` quando presente. Use backoff exponencial com jitter quando ele não estiver presente. Não responda reenviando todas as chamadas de ferramentas em fila de uma só vez: em vez disso, reduza quantas você executa em paralelo.
- **Preserve o escopo e tente novamente mais tarde**: `no_eligible_proxy`. Não remova `exitCountries` nem substitua outro país silenciosamente. Altere ou amplie a allowlist apenas quando o usuário alterar explicitamente o requisito.
- **Não tente novamente até que a entrada ou a credencial seja corrigida**: `bad_request`, `auth_failed`, `not_found`, `ssrf_blocked`. Para `auth_failed`, verifique a chave de API da FourA, não as credenciais do site de destino.
- **Troque de ferramenta quando o conteúdo exigir**: `forbidden` em `foura_single` pode justificar uma tentativa delimitada de `foura_proxy`. Use `foura_browser` quando o conteúdo desejado precisar de JavaScript. Após uma seleção de proxy bem-sucedida, passe o ID de `proxy` retornado para `foura_browser.proxy` em vez de iniciar uma nova seleção.

## Exemplo de repetição (TypeScript, lado do MCP)

```typescript
async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}
```

## Relacionados

- [MCP Server](https://foura.ai/docs/mcp/server), as quatro ferramentas e seus schemas
- [MCP Recipes](https://foura.ai/docs/mcp/recipes), prompts de fluxo de trabalho enviados com o servidor
- [API Errors](https://foura.ai/docs/api/errors), o mesmo envelope na camada subjacente da REST API
- [Rate Limits](https://foura.ai/docs/api/rate-limits), os limites de conta e plataforma por trás de `rate_limited` e `at_capacity`
