MCP 서버 오류

foura-mcp server가 반환하는 오류 처리 방법입니다.

네 가지 도구(foura_auto, foura_single, foura_proxy, foura_browser)의 모든 오류 응답은 구조화되어 있습니다. LLM 에이전트는 일반 텍스트를 파싱할 필요 없이 code 필드를 읽어 재시도 로직을 수행할 수 있습니다.

Envelope 구조

모든 오류(isError: true)에는 structuredContent 블록이 포함됩니다. 모든 오류의 최소 필드:

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

HTTP status를 동반한 업스트림 오류의 경우, status도 존재합니다. rate limit 및 용량 오류의 경우, 엔벨로프는 기본 REST API 오류와 동일한 형태의 retryAfter, current.{concurrency, rpm}, limits.{maxConcurrency, maxRpm}을 추가합니다.

안정적인 `code` 값

Code	HTTP	의미	재시도 안전?
`ssrf_blocked`	해당 없음	프라이빗 또는 예약된 범위의 대상 IP(RFC 5735, RFC 6598, IPv6 예약됨)	아니요, URL을 변경하세요
`upstream_non_json`	다양함	업스트림이 유효한 JSON이 아닌 본문을 반환함	아마도, 조사 필요
`output_validation_failed`	해당 없음	MCP 서버의 `outputSchema`가 업스트림 응답을 거부함(서버 버그 또는 예상치 못한 업스트림 형태)	아마도, 보고 필요
`bad_request`	400	FourA API에 의해 입력 형태가 거부됨	아니요, 인수를 수정하세요
`auth_failed`	401	FourA API 키가 누락되었거나 유효하지 않거나 비활성화됨. 대상 사이트 자격 증명에 관한 것이 아님	아니요, FourA 키를 수정하세요
`forbidden`	403	대상이 요청을 거부함(안티봇, 지역 차단)	아니요, 또는 `foura_proxy`로 전환하세요
`not_found`	404	대상 URL 또는 endpoint가 존재하지 않음	아니요
`rate_limited`	429	키당 RPM 한도 초과	예, `retryAfter`초 대기
`at_capacity`	503	동시성 한도 초과(`current.concurrency` > `limits.maxConcurrency`)	예, `retryAfter`초 대기
`service_disabled`	503	계정에 대해 서비스가 비활성화됨(플랜 또는 유지보수)	지원팀에 문의
`service_unavailable`	503	업스트림에서 일반적인 503	예, 짧은 백오프
`upstream_error`	500+	업스트림 5xx	예, 지수 백오프
`upstream_client_error`	4xx	위에서 다루지 않은 기타 4xx	대개 아니요
`upstream_unknown`	기타	방어적, 실제로는 발생하지 않아야 함	조사 필요
`no_eligible_proxy`	해당 없음	엄격한 `exitCountries` 허용 목록과 일치하는 proxy가 없음. `details.exitCountries`에는 정규화된 범위가 포함됨	나중에 재시도. 명시적으로만 범위 변경

MCP 서버의 HTTP 수준 오류

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

HTTP	시기	표시 내용
400	지원되지 않는 `MCP-Protocol-Version` header	`Unsupported MCP-Protocol-Version: <value>. Supported: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.`
401	누락되거나 잘못된 형식의 `Authorization` header	JSON-RPC 오류 + `WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`
403	허용되지 않는 `Origin` 또는 `Host` header(DNS 리바인딩 방어, CVE-2025-66414)	`Origin <value> is not in the allowlist` 또는 `Host <value> is not in the allowlist`
405	`/mcp`(무상태 모드)의 `GET` 또는 `DELETE`	`Method not allowed in stateless mode. Use POST /mcp.`
413	Request 본문 > 256KB	Express 기본 413

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

거부된 브라우저 프로필

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

이는 서비스 중단이 아니라 거부입니다. 동일한 request를 재시도해도 성공할 수 없으며, 다른 브라우저가 대신 사용되지도 않습니다.

재시도 전략

네 가지 범주:

대기 후 재시도: rate_limited, at_capacity, service_unavailable, upstream_error. retryAfter이 있는 경우 이를 준수하십시오. 없는 경우 지터(jitter)와 함께 지수 백오프(exponential backoff)를 사용하십시오.
범위 유지 및 나중에 재시도: no_eligible_proxy. exitCountries을 제거하거나 조용히 다른 국가로 대체하지 마십시오. 사용자가 명시적으로 요구 사항을 변경할 때만 허용 목록을 변경하거나 확장하십시오.
입력 또는 자격 증명이 수정될 때까지 재시도 금지: bad_request, auth_failed, not_found, ssrf_blocked. auth_failed의 경우 대상 사이트 자격 증명이 아닌 FourA API 키를 확인하십시오.
콘텐츠에 필요한 경우 도구 전환: foura_single에 대한 forbidden은 제한된 foura_proxy 시도를 정당화할 수 있습니다. 원하는 콘텐츠에 JavaScript가 필요한 경우 foura_browser를 사용하십시오. 성공적인 proxy 선택 후, 새로운 선택을 시작하는 대신 반환된 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 서버 오류

MCP 서버 오류

Envelope 구조

안정적인 code 값

MCP 서버의 HTTP 수준 오류

거부된 브라우저 프로필

재시도 전략

재시도 예제 (TypeScript, MCP 측)

관련 항목

안정적인 `code` 값