Erros do Servidor MCP

Como tratar erros retornados pelo servidor foura-mcp.

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:

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

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)

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");
}
  • MCP Server, as quatro ferramentas e seus schemas
  • MCP Recipes, prompts de fluxo de trabalho enviados com o servidor
  • API Errors, o mesmo envelope na camada subjacente da REST API
  • Rate Limits, os limites de conta e plataforma por trás de rate_limited e at_capacity
Atualizado em: 13 de novembro de 2026