Грешки на MCP сървъра
Как да обработвате грешки, върнати от foura-mcp server.
Всеки отговор за грешка от който и да е от четирите инструмента (foura_auto, foura_single, foura_proxy, foura_browser) е структуриран. LLM агентите могат да четат полето code за логика за повторен опит, без да анализират свободен текст.
Структура на обвивката
Всяка грешка (isError: true) съдържа блок structuredContent. Минимални полета за всяка грешка:
{
"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.
Когато някой от лимитите на вашия план откаже извикване, кодът Е този лимит: 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.
Това са откази, а не прекъсвания на услугата: повторното изпращане на идентична заявка не може да успее и на нейно място не е използван друг браузър.
Стратегия за повторни опити
Пет категории:
- Вашият собствен план го отказа, а не целевият сайт: всеки
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, подайте върнатияproxyID въвfoura_browser.proxy, вместо да стартирате нов избор.
Retry пример (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, четирите инструмента и техните схеми
- MCP Recipes, промптове за работни процеси, включени в сървъра
- API Errors, същата структура при базовия REST API слой
- Rate Limits, лимитите за акаунта и платформата зад
rate_limitedиat_capacity