Ошибки MCP-сервера
Как обрабатывать ошибки, возвращаемые сервером foura-mcp.
Каждый ответ с ошибкой от любого из четырех инструментов (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. Когда общий лимит платформы отклоняет вызов, envelope добавляет retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm} в том же формате, что и базовые ошибки REST API.
Когда вызов отклоняется из-за лимита вашего тарифного плана, код указывает именно на этот лимит: 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.
Это именно отказы, а не сбои в работе сервиса: повтор идентичного запроса завершится ошибкой, и никакой другой браузер взамен использован не был.
Стратегия повторных попыток
Пять категорий:
- Запрос отклонен вашим тарифным планом, а не целевым ресурсом: любой код
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)
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