Erros do servidor MCP

Como lidar com 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 LLM podem ler o campo code para lógica de repetição sem analisar texto.

Formato do envelope

Todo erro (isError: true) carrega 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. Em erros de rate limit e capacidade, o envelope adiciona retryAfter, current.{concurrency, rpm} e limits.{maxConcurrency, maxRpm}, com o mesmo formato dos erros da API REST subjacentes.

Valores estáveis de code

Erros no nível do HTTP do servidor MCP

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

As allowlists para o erro 403 são configuráveis por ambiente para self-hosters usando FOURA_MCP_ALLOWED_HOSTS e FOURA_MCP_ALLOWED_ORIGINS.

Perfis de navegador recusados

Um perfil de navegador que o catálogo não pode apresentar, ou um perfil enviado com unblocker definido como false, retorna como uma falha de upstream com o motivo em error e a request nunca sai do FourA. A mensagem nomeia o que está disponível, então tente novamente com uma das combinações listadas em vez da mesma.

Estas são recusas, não interrupções: tentar a mesma request novamente não pode ter sucesso, e nenhum outro navegador foi usado em seu lugar.

Estratégia de nova tentativa

Quatro categorias:

• Aguarde e tente novamente: rate_limited, at_capacity, service_unavailable, upstream_error. Respeite retryAfter quando presente. Use exponential backoff com jitter quando estiver ausente.
• 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 credencial seja corrigida: bad_request, auth_failed, not_found, ssrf_blocked. Para auth_failed, verifique a chave de API do FourA, não as credenciais do site de destino.
• Mude de ferramenta quando o conteúdo exigir: forbidden em foura_single pode justificar uma tentativa limitada 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 proxy retornado para foura_browser.proxy em vez de iniciar uma nova seleção.

Exemplo de nova tentativa (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");
}

Relacionados

• Servidor MCP, as quatro ferramentas e seus schemas
• Receitas MCP, prompts de fluxo de trabalho incluídos no servidor
• Erros da API, mesmo envelope na camada da API REST subjacente