# Ошибки MCP-сервера

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

Как обрабатывать ошибки, возвращаемые сервером [foura-mcp](https://foura.ai/docs/mcp/server).

Каждый ответ с ошибкой от любого из четырех инструментов (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) является структурированным. LLM-агенты могут считывать поле `code` для логики повторных попыток без парсинга обычного текста.

## Структура конверта

Каждая ошибка (`isError: true`) содержит блок `structuredContent`. Минимальный набор полей для каждой ошибки:

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

При ошибках upstream с HTTP-статусом также присутствует `status`. Когда общий лимит платформы отклоняет вызов, envelope добавляет `retryAfter`, `current.{concurrency, rpm}` и `limits.{maxConcurrency, maxRpm}` в том же формате, что и базовые [ошибки REST API](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` | различается | Upstream вернул тело, которое не является валидным JSON | Возможно, требуется анализ |
| `output_validation_failed` | н/д | `outputSchema` на MCP-сервере отклонил ответ upstream, либо инструмент не смог завершить вызов (API key не настроен, API недоступен) | Возможно: проверьте настройки, затем отправьте отчет |
| `bad_request` | 400 | Формат входных данных отклонен FourA API, целевой URL указывает на собственный API FourA вместо страницы (через него можно запрашивать только `/inspect`), URL содержит некодированный пробел (закодируйте его как `%20`), либо `proxy` указывает exit, который данный вызов не может использовать: premium exit при исчерпанном premium-трафике возвращает `Managed exit: this proxy id cannot be pinned to a request`. Запрос не выполняется, списания не происходят | Нет, исправьте аргументы |
| `auth_failed` | 401 | FourA API key отсутствует, недействителен или деактивирован; это не относится к учетным данным целевого сайта | Нет, исправьте ключ FourA |
| `forbidden` | 403 | Целевой ресурс вернул 403, и ваш `validate` отклонил его (проверка сайта, ограничение по стране) | Нет, или переключитесь на `foura_proxy` |
| `not_found` | 404 | Целевой URL или endpoint не существует | Нет |
| `rate_limited` | 429 | Общий поминутный лимит платформы, либо ответ 429 от целевого ресурса, который ваш `validate` отклонил. На `foura_auto` это также могут быть кредиты вашего плана, трафик или rate limit (см. `reason`) | Да, подождите `retryAfter`, если он присутствует, иначе примените backoff |
| `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 | Да, короткий backoff |
| `upstream_error` | 500+ или 0 | Целевой ресурс вернул ошибку сервера, либо на `foura_proxy`, `foura_browser` и `foura_auto` ответ так и не был получен | Да, экспоненциальный backoff |
| `upstream_client_error` | 4xx | Другие ошибки 4xx, не указанные выше | Обычно нет |
| `upstream_unknown` | другое | Запрос выполнен, но не дал принятого ответа: на `foura_single` целевой ресурс так и не ответил (таймаут, сброс соединения), а на любом инструменте ваш `validate` отклонил ответ 2xx или 3xx. См. `status` и `error` | Требуется анализ |
| `no_eligible_proxy` | н/д | Ни один proxy не соответствует строгому списку разрешений `exitCountries`; `details.exitCountries` содержит нормализованный scope | Повторите позже; меняйте scope только явно |
| `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"` на плане, который не включает premium exits | Нет, удалите параметр или измените план |
| `plan_limit_feature` | 403 | План не включает данный endpoint или эту возможность | Нет, измените план |

## Ошибки уровня HTTP от MCP-сервера

Некоторые сбои происходят на транспортном уровне 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-rebinding, CVE-2025-66414) | `Origin <value> is not in the allowlist` или `Host <value> is not in the allowlist` |
| 405 | `GET` или `DELETE` на `/mcp` (stateless-режим) | `Method not allowed in stateless mode. Use POST /mcp.` |
| 413 | Тело запроса > 256 KB | Стандартный 413 от Express |

Списки разрешений для 403 настраиваются через переменные окружения `FOURA_MCP_ALLOWED_HOSTS` и `FOURA_MCP_ALLOWED_ORIGINS` при самостоятельном хостинге.

## Отклоненные профили браузера

Профиль браузера, отсутствующий в каталоге, или профиль, переданный со значением `unblocker` равным `false`, возвращается как сбой upstream с указанием причины в `error`, и запрос не покидает FourA. Если комбинация `browser`, `os` и `version` не существует, в сообщении перечисляются доступные варианты, поэтому повторите запрос с одной из указанных комбинаций вместо прежней. Неизвестный идентификатор `profile` возвращает `unknown profile` без списка: найдите идентификатор в [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles).

Это именно отказы, а не сбои в работе сервиса: повтор идентичного запроса завершится ошибкой, и никакой другой браузер взамен использован не был.

## Стратегия повторных попыток

Пять категорий:

- **Запрос отклонен вашим тарифным планом, а не целевым ресурсом**: любой код `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`, если он передан. Используйте экспоненциальную задержку с джиттером (exponential backoff with jitter), если он отсутствует. Не отвечайте на это одновременным повторным запуском всех вызовов инструментов из очереди: вместо этого уменьшите количество параллельно выполняемых запросов.
- **Сохранить область видимости и повторить попытку позже**: `no_eligible_proxy`. Не удаляйте `exitCountries` и не подменяйте страну не предупредив. Изменяйте или расширяйте allowlist только тогда, когда пользователь явно изменил требование.
- **Не повторять попытку до исправления входных данных или учетных данных**: `bad_request`, `auth_failed`, `not_found`, `ssrf_blocked`. Для `auth_failed` проверьте API key сервиса FourA, а не учетные данные целевого сайта.
- **Сменить инструмент, когда этого требует контент**: `forbidden` на `foura_single` может оправдать ограниченную попытку с `foura_proxy`. Используйте `foura_browser`, когда нужный контент требует JavaScript. После успешного выбора proxy передайте возвращенный идентификатор `proxy` в `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), четыре инструмента и их схемы
- [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`
