Erros do MCP Server

Como tratar erros retornados pelo servidor foura-mcp.

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

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 o limite compartilhado da plataforma recusa uma chamada, o envelope adiciona retryAfter, current.{concurrency, rpm} e limits.{maxConcurrency, maxRpm}, no 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 traz o tempo de espera quando a espera resolve o problema, e fica ausente para um limite que a espera não pode resolver, como um recurso que o plano não inclui. plan_limit_browser_daily também não traz retryAfter: ele é redefinido à meia-noite UTC.

Em foura_auto, um limite de plano atingido dentro de sua escala retorna como rate_limited ou forbidden, com o código do plano em reason.

Valores estáveis de code

Erros de nível HTTP do servidor MCP

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

As allowlists para 403 são configuráveis via variáveis de ambiente para quem utiliza self-hosting por meio de 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 requisição nunca sai do FourA. A mensagem informa o que está disponível, portanto, tente novamente com uma das combinações listadas em vez da mesma.

Estas são recusas, não interrupções do serviço: repetir a requisição idêntica não terá sucesso, e nenhum outro navegador foi utilizado em seu lugar.

Estratégia de repetição

Cinco categorias:

• O seu próprio plano recusou, não o destino: qualquer código plan_limit_*. O mesmo trabalho por meio de outra ferramenta também será recusado, portanto, alternar endpoints apenas desperdiça tempo. Aguarde o retryAfter quando houver um; caso contrário, o plano precisa mudar. plan_limit_premium é o único 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 não estiver presente. Não responda a isso 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 por 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 do FourA, não as credenciais do site de destino.
• Alterne a 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 bem-sucedida de proxy, passe o ID 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");
}

Relacionados

• MCP Server, as quatro ferramentas e seus schemas
• MCP Recipes, prompts de fluxo de trabalho incluídos com o servidor
• Erros de API, mesmo envelope na camada REST API subjacente
• Rate Limits, os limites de conta e plataforma por trás de rate_limited e at_capacity