MCP Server 에러

foura-mcp server에서 반환된 에러를 처리하는 방법입니다.

4개 도구(foura_auto, foura_single, foura_proxy, foura_browser)의 모든 에러 response는 정형화되어 있습니다. LLM 에이전트는 줄글을 파싱할 필요 없이 재시도 로직에 code 필드를 읽어 사용할 수 있습니다.

Envelope 구조

모든 에러(isError: true)에는 structuredContent 블록이 포함됩니다. 모든 에러의 최소 필드는 다음과 같습니다.

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

HTTP 상태 코드가 있는 업스트림 오류의 경우 status도 함께 제공됩니다. 플랫폼의 공유 한도로 인해 호출이 거부되면 엔벨로프에 retryAfter, current.{concurrency, rpm}, limits.{maxConcurrency, maxRpm}가 추가되며 기본 REST API 오류와 동일한 구조를 갖습니다.

플랜 자체의 한도로 인해 호출이 거부되는 경우 코드는 해당 한도 자체를 나타냅니다. plan_limit_ 뒤에 credits, bandwidth, rate, concurrency, browser_daily, premium 또는 feature가 붙습니다. 대기하여 해결될 수 있는 경우 retryAfter에 대기 시간이 포함되며, 플랜에 포함되지 않은 기능처럼 대기로 해결할 수 없는 한도에는 포함되지 않습니다. plan_limit_browser_daily 역시 retryAfter를 포함하지 않으며, 자정 UTC에 초기화됩니다.

foura_auto의 경우 사다리 내에서 플랜 한도에 도달하면 rate_limited 또는 forbidden로 반환되며, reason에 플랜 코드가 포함됩니다.

고정 code 값

MCP 서버의 HTTP 수준 오류

일부 실패는 도구가 호출되기 전 MCP 전송 계층에서 발생합니다. 이러한 실패는 원시 JSON-RPC 오류를 반환합니다 (structuredContent 없음):

403 허용 목록은 자체 호스팅 사용자를 위해 FOURA_MCP_ALLOWED_HOSTS 및 FOURA_MCP_ALLOWED_ORIGINS 환경 변수로 구성할 수 있습니다.

거부된 브라우저 프로필

카탈로그에서 제공할 수 없는 브라우저 프로필이거나 unblocker이 false로 설정되어 전송된 프로필은 error에 이유가 포함된 업스트림 실패로 반환되며 요청은 FourA를 떠나지 않습니다. 메시지에 사용 가능한 항목이 명시되므로 동일한 조합 대신 나열된 조합 중 하나로 재시도하세요.

이는 장애가 아닌 거부입니다. 동일한 요청을 다시 시도해도 성공할 수 없으며 다른 브라우저가 대신 사용되지도 않았습니다.

재시도 전략

5가지 범주:

• 타깃이 아닌 사용자의 플랜에서 거부됨: 모든 plan_limit_* 코드. 다른 도구를 통한 동일한 작업도 거부되므로 엔드포인트를 변경하는 것은 시간만 낭비하게 됩니다. retryAfter 값이 있으면 대기하고, 그렇지 않으면 플랜을 변경해야 합니다. plan_limit_premium는 exitClass를 제거하여 직접 해결할 수 있는 유일한 항목입니다.
• 대기 후 재시도: rate_limited, at_capacity, service_unavailable, upstream_error. retryAfter가 있으면 이를 준수하세요. 없는 경우 지터를 적용한 지수 백오프를 사용하세요. 대기 중인 모든 도구 호출을 한 번에 다시 실행하지 말고, 병렬 실행 수를 줄이세요.
• 범위를 유지하고 나중에 재시도: no_eligible_proxy. exitCountries를 제거하거나 다른 국가로 임의 대체하지 마세요. 사용자가 명시적으로 요구 사항을 변경할 때만 허용 목록을 변경하거나 확장하세요.
• 입력 또는 인증 정보가 수정될 때까지 재시도 금지: bad_request, auth_failed, not_found, ssrf_blocked. auth_failed의 경우 타깃 사이트 인증 정보가 아니라 FourA API key를 확인하세요.
• 콘텐츠 요구 사항에 따라 도구 전환: foura_single에서의 forbidden는 제한적인 foura_proxy 시도를 정당화할 수 있습니다. 원하는 콘텐츠에 JavaScript가 필요한 경우 foura_browser를 사용하세요. 프록시 선택이 성공한 후에는 새 선택을 시작하지 말고 반환된 proxy ID를 foura_browser.proxy에 전달하세요.

재시도 예시 (TypeScript, 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, 4가지 도구 및 해당 스키마
• MCP Recipes, 서버와 함께 제공되는 워크플로 프롬프트
• API Errors, 기본 REST API 계층의 동일한 엔벨로프
• Rate Limits, rate_limited 및 at_capacity 기반의 계정 및 플랫폼 제한