# Грешки на MCP сървъра

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

Как да обработвате грешки, върнати от [foura-mcp server](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` също присъства. Когато споделеният лимит на платформата откаже извикване, обвивката добавя `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` | n/a | Целта е частен или резервиран адрес (RFC 5735, RFC 6598, IPv6 reserved), URL адресът не е http(s), или името на хоста не се разреши | Не, проверете URL адреса. Краткотрайно неуспешно търсене може да бъде повторено |
| `upstream_non_json` | варира | Upstream услугата върна тяло, което не е валиден JSON | Възможно е, проучете |
| `output_validation_failed` | n/a | Сървърът MCP на `outputSchema` отхвърли upstream отговора, или инструментът не успя да завърши извикването изобщо (няма конфигуриран API ключ, API е недостъпен) | Възможно е: проверете конфигурацията, след това докладвайте |
| `bad_request` | 400 | Форматът на входните данни е отхвърлен от FourA API, целевият URL сочи към собствения API на FourA вместо към страница (само `/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`, когато е наличен, в противен случай направете 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` | n/a | Няма proxy, съответстващо на строгия `exitCountries` списък с разрешени; `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 или тази функционалност | Не, сменете плана |

## Грешки на HTTP ниво от MCP сървъра

Някои грешки възникват на транспортния слой на MCP, преди извикването на какъвто и да е инструмент. Те връщат необработени JSON-RPC грешки (без `structuredContent`):

| HTTP | Кога | Какво виждате |
|---|---|---|
| 400 | Неподдържан `MCP-Protocol-Version` header | `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 key. Извеждането на инструменти и prompts работи без такъв | JSON-RPC грешка + `WWW-Authenticate: Bearer realm="foura-mcp"` |
| 403 | Забранен `Origin` или `Host` header (защита срещу 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 | Request body > 256 KB | Express по подразбиране 413 |

Списъците с позволени стойности за 403 могат да се конфигурират чрез променливи на средата за self-hosters чрез `FOURA_MCP_ALLOWED_HOSTS` и `FOURA_MCP_ALLOWED_ORIGINS`.

## Отхвърлени браузърни профили

Браузърен профил, който каталогът не може да предостави, или профил, изпратен с `unblocker` със стойност `false`, се връща като upstream грешка с причината в `error` и заявката изобщо не напуска FourA. За несъществуваща комбинация от `browser`, `os` и `version` съобщението посочва наличните варианти, така че опитайте отново с някоя от изброените комбинации вместо със същата. Неизвестен `profile` id връща `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 с jitter, когато липсва. Не отговаряйте, като пускате отново всички извиквания на инструменти наведнъж: вместо това намалете броя на паралелно изпълняваните.
- **Запазете обхвата и опитайте отново по-късно**: `no_eligible_proxy`. Не премахвайте `exitCountries` и не заменяйте мълчаливо с друга държава. Променяйте или разширявайте allowlist само когато потребителят изрично промени изискването.
- **Не опитвайте отново, докато входните данни или идентификационните данни не бъдат коригирани**: `bad_request`, `auth_failed`, `not_found`, `ssrf_blocked`. За `auth_failed` проверете FourA API ключа, а не идентификационните данни за целевия сайт.
- **Сменете инструмента, когато съдържанието го изисква**: `forbidden` при `foura_single` може да оправдае ограничен `foura_proxy` опит. Използвайте `foura_browser`, когато желаното съдържание изисква JavaScript. След успешен избор на proxy, подайте върнатия `proxy` ID във `foura_browser.proxy`, вместо да стартирате нов избор.

## Retry пример (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`
