MCP 서버 오류
foura-mcp server에서 반환된 오류를 처리하는 방법입니다.
4가지 도구(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도 함께 제공됩니다. 플랫폼의 공유 한도로 인해 호출이 거부되면 엔벨로프에 retryAfter, current.{concurrency, rpm}, limits.{maxConcurrency, maxRpm}이 추가되며, 이는 기본 REST API errors와 동일한 형태입니다.
플랜 자체의 제한으로 인해 호출이 거부되는 경우, 오류 코드가 바로 해당 제한 항목을 나타냅니다. plan_limit_ 뒤에 credits, bandwidth, rate, concurrency, browser_daily, premium 또는 feature가 이어집니다. 대기 후 해결될 수 있는 제한의 경우 retryAfter에 대기 시간이 포함되며, 플랜에 포함되지 않은 기능처럼 대기로 해결할 수 없는 제한의 경우에는 제공되지 않습니다. plan_limit_browser_daily 역시 retryAfter을 포함하지 않으며 UTC 자정에 초기화됩니다. plan_limit_credits 및 plan_limit_bandwidth는 retryAfter을 최대 24시간으로 제한하고 청구 기간의 정확한 종료 시점인 resets_at을 추가하므로, 재시도를 예약하기 전에 resets_at를 확인하십시오.
foura_auto에서 사다리 단계 내 플랜 제한에 도달하면 rate_limited 또는 forbidden로 반환되며, reason에 플랜 코드가 포함됩니다.
안정적인 code 값
| 코드 | HTTP | 의미 | 재시도 안전 여부 |
|---|---|---|---|
ssrf_blocked |
해당 없음 | 대상이 비공개 또는 예약된 주소이거나(RFC 5735, RFC 6598, IPv6 예약), URL이 http(s)가 아니거나, 호스트 이름이 확인되지 않았습니다 | 아니요, URL을 확인하십시오. 일시적으로 실패한 조회는 재시도할 수 있습니다 |
upstream_non_json |
다양함 | 업스트림에서 유효한 JSON이 아닌 본문을 반환했습니다 | 재시도 가능, 원인을 조사하십시오 |
output_validation_failed |
해당 없음 | MCP 서버의 outputSchema이(가) 업스트림 응답을 거부했거나 도구가 호출을 전혀 완료할 수 없었습니다(API 키가 구성되지 않음, API에 접근할 수 없음) |
재시도 가능: 설정을 확인한 다음 보고하십시오 |
bad_request |
400 | FourA API에서 거부된 입력 형식이거나, 대상 URL이 페이지 대신 FourA 자체 API를 가리키거나(해당 위치에서는 /inspect만 가져올 수 있음), URL 내부에 인코딩되지 않은 공백이 있거나(%20(으)로 인코딩 필요), proxy이(가) 호출에서 사용할 수 없는 출구를 지정했습니다. 프리미엄 트래픽을 모두 소진한 후 프리미엄 출구를 요청하면 Managed exit: this proxy id cannot be pinned to a request이(가) 반환됩니다. 아무것도 가져오지 않으며 요금도 청구되지 않습니다 |
아니요, 인수를 수정하십시오 |
auth_failed |
401 | FourA API 키가 누락되었거나 유효하지 않거나 비활성화되었습니다. 대상 사이트의 인증 정보와는 관련이 없습니다 | 아니요, FourA 키를 수정하십시오 |
forbidden |
403 | 대상이 403 응답을 반환했고 validate에서 이를 거부했습니다(사이트 검사, 국가 제한) |
아니요, 또는 foura_proxy(으)로 전환하십시오 |
not_found |
404 | 대상 URL 또는 endpoint가 존재하지 않습니다 | 아니요 |
rate_limited |
429 | 플랫폼의 공유 분당 허용량이거나, 대상의 429 응답을 validate에서 거부했습니다. foura_auto에서는 플랜의 크레딧, 트래픽 또는 rate limit일 수도 있습니다(reason 참조) |
예, retryAfter 값이 있으면 대기하고, 그렇지 않으면 백오프하십시오 |
at_capacity |
503 | 동시성 한도에 도달했거나(current.concurrency > limits.maxConcurrency), 유지보수를 위해 서비스가 꺼져 있습니다(error은 Service disabled, retryAfter은(는) 60) |
예, retryAfter초 대기하십시오 |
service_disabled |
503 | 예약됨. 유지보수를 위해 꺼진 서비스는 현재 at_capacity(으)로 반환되며, 플랜에 포함되지 않은 도구는 plan_limit_feature(으)로 반환됩니다 |
고객 지원팀에 문의하십시오 |
service_unavailable |
503 | 업스트림의 일반적인 503 응답 | 예, 짧게 백오프하십시오 |
upstream_error |
500+ 또는 0 | 대상이 서버 오류로 응답했거나, foura_proxy에서 foura_browser 및 foura_auto이(가) 응답하지 않았습니다 |
예, 지수 백오프하십시오 |
upstream_client_error |
4xx | 위에 포함되지 않은 기타 4xx | 보통 아니요 |
upstream_unknown |
기타 | 요청이 실행되었지만 수락 가능한 응답이 생성되지 않았습니다. foura_single에서는 대상이 응답하지 않았으며(시간 초과, 연결 거부), 임의의 도구에서 validate이(가) 2xx 또는 3xx 응답을 거부했습니다. status 및 error을(를) 확인하십시오 |
원인을 조사하십시오 |
no_eligible_proxy |
해당 없음 | 엄격한 exitCountries 허용 목록과 일치하는 proxy가 없습니다. details.exitCountries에 정규화된 범위가 포함됩니다 |
나중에 재시도하십시오. 범위 변경은 명시적인 경우에만 수행하십시오 |
plan_limit_credits |
429 | 플랜의 월간 크레딧을 모두 소진했습니다 | 예, retryAfter 이후 재시도하거나 플랜을 변경하십시오 |
plan_limit_bandwidth |
429 | 이번 청구 기간에 대한 플랜의 트래픽 허용량을 모두 소진했습니다 | 예, retryAfter 이후 재시도하거나 플랜을 변경하십시오 |
plan_limit_rate |
429 | 해당 endpoint에 대한 플랜의 분당 요청 한도입니다 | 예, retryAfter 이후 재시도하십시오 |
plan_limit_concurrency |
429 | 해당 endpoint에 대한 플랜의 동시 요청 한도입니다 | 예, retryAfter 이후 재시도하십시오 |
plan_limit_browser_daily |
429 | 플랜의 일일 Browser 허용량을 모두 소진했습니다 | 예, 내일 재시도하거나 foura_single / foura_proxy을(를) 사용하십시오 |
plan_limit_premium |
403 | 프리미엄 출구가 포함되지 않은 플랜에서 exitClass: "premium"을(를) 전송했습니다 |
아니요, 매개변수를 제거하거나 플랜을 변경하십시오 |
plan_limit_feature |
403 | 플랜이 해당 endpoint 또는 기능을 지원하지 않습니다 | 아니요, 플랜을 변경하십시오 |
MCP 서버의 HTTP 수준 오류
일부 장애는 도구가 호출되기 전, MCP 전송 계층에서 발생합니다. 이러한 오류는 원시 JSON-RPC 오류를 반환합니다(structuredContent 없음):
| HTTP | 발생 조건 | 표시 내용 |
|---|---|---|
| 400 | 지원되지 않는 MCP-Protocol-Version 헤더 |
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 | API 키 없이 도구 호출 또는 리소스 읽기 시도. 도구 및 프롬프트 목록 조회는 키 없이도 작동함 | JSON-RPC 오류 + WWW-Authenticate: Bearer realm="foura-mcp" |
| 403 | 허용되지 않은 Origin 또는 Host 헤더 (DNS 리바인딩 방어, CVE-2025-66414) |
Origin <value> is not in the allowlist 또는 Host <value> is not in the allowlist |
| 405 | /mcp(stateless 모드)에서의 GET 또는 DELETE |
Method not allowed in stateless mode. Use POST /mcp. |
| 413 | 요청 본문 > 256 KB | Express 기본 413 |
403에 대한 허용 목록은 자체 호스팅 환경에서 FOURA_MCP_ALLOWED_HOSTS 및 FOURA_MCP_ALLOWED_ORIGINS 환경 변수를 통해 구성할 수 있습니다.
거부된 브라우저 프로필
카탈로그에서 제공할 수 없는 브라우저 프로필이거나 unblocker가 false로 설정되어 전송된 프로필은 error에 사유가 포함된 업스트림 장애로 반환되며, 요청은 FourA를 떠나지 않습니다. 존재하지 않는 browser, os, version 조합의 경우 메시지에 사용 가능한 항목이 명시되므로 동일한 조합 대신 나열된 조합 중 하나로 재시도하십시오. 알 수 없는 profile ID는 목록 없이 unknown profile를 받게 됩니다. ID는 GET /api/profiles에서 확인하십시오.
이는 서비스 중단이 아닌 명시적 거부입니다. 동일한 요청을 재시도해도 성공할 수 없으며, 다른 브라우저가 대신 사용되지도 않았습니다.
재시도 전략
5가지 범주:
- 대상이 아닌 사용자의 플랜에서 거부됨: 모든
plan_limit_*코드.plan_limit_credits및plan_limit_bandwidth은 계정 전체 기준으로 집계되므로 다른 도구를 통한 동일한 작업도 거부됩니다.plan_limit_rate,plan_limit_concurrency,plan_limit_browser_daily,plan_limit_feature은 단일 endpoint에 적용되므로 해당 작업을 수행할 수 있는 다른 도구가 있다면 계속 실행할 수 있습니다.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 선택이 성공한 후에는 새로 선택을 시작하는 대신 반환된proxyID를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기반의 계정 및 플랫폼 제한