# MCP 서버 오류

> URL: https://foura.ai/ko/docs/mcp/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

[foura-mcp server](https://foura.ai/docs/mcp/server)에서 반환된 오류를 처리하는 방법입니다.

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

## Envelope 형태

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

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

HTTP 상태가 포함된 업스트림 오류 발생 시 `status`도 함께 제공됩니다. 플랫폼의 공유 한도로 인해 호출이 거부되면 엔벨로프에 `retryAfter`, `current.{concurrency, rpm}`, `limits.{maxConcurrency, maxRpm}`이 추가되며, 이는 기본 [REST API errors](https://foura.ai/docs/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`](https://foura.ai/docs/api/endpoints#browser-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 선택이 성공한 후에는 새로 선택을 시작하는 대신 반환된 `proxy` ID를 `foura_browser.proxy`에 전달하십시오.

## 재시도 예시 (TypeScript, MCP 측)

```typescript
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](https://foura.ai/docs/mcp/server), 4가지 도구 및 스키마
- [MCP Recipes](https://foura.ai/docs/mcp/recipes), 서버와 함께 제공되는 워크플로 프롬프트
- [API Errors](https://foura.ai/docs/api/errors), 기본 REST API 레이어의 동일한 엔벨로프
- [Rate Limits](https://foura.ai/docs/api/rate-limits), `rate_limited` 및 `at_capacity` 기반의 계정 및 플랫폼 제한
