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_creditseplan_limit_bandwidthcontabilizam 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_dailyeplan_limit_featureaplicam-se a um endpoint, portanto outra ferramenta ainda pode ser executada se puder realizar o trabalho. Aguarde oretryAfterquando houver um; caso contrário, o plano precisa mudar.plan_limit_premiumé o que você mesmo pode resolver, removendoexitClass. - Aguarde e tente novamente:
rate_limited,at_capacity,service_unavailable,upstream_error. RespeiteretryAfterquando 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 removaexitCountriesnem 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. Paraauth_failed, verifique a chave de API da FourA, não as credenciais do site de destino. - Troque de ferramenta quando o conteúdo exigir:
forbiddenemfoura_singlepode justificar uma tentativa delimitada defoura_proxy. Usefoura_browserquando o conteúdo desejado precisar de JavaScript. Após uma seleção de proxy bem-sucedida, passe o ID deproxyretornado parafoura_browser.proxyem 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 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_limitedeat_capacity