Ошибки API
Как обрабатывать ошибки API FourA.
Формат ответа с ошибкой
API возвращает плоские объекты JSON для всех ошибок. Вложенный объект error отсутствует. Если у сбоя есть машиночитаемый код, он находится в поле верхнего уровня: reason при превышении лимита тарифа, code при вызове proxy без подходящего выхода.
{
"error": "Invalid API key"
}
Некоторые ошибки содержат дополнительные поля, такие как status, service, retryAfter, current или limits на верхнем уровне:
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": { "concurrency": 12, "rpm": 3000 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Отслеживание request
Каждый API response (успешный или с ошибкой) содержит header X-FourA-Request-Id с UUID для этого вызова, за исключением случаев, когда FourA вовсе не может прочитать body (некорректный JSON или body более 100 KB): такие запросы отклоняются до назначения ID. Логируйте его на своей стороне. Если вам потребуется уточнить у поддержки статус конкретного request, этот ID позволит нам его найти.
curl -i -X POST https://eu.api.foura.ai/api/single/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "GET", "url": "https://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
Типы ошибок
400: Некорректный запрос
Тело request не содержит обязательных полей, содержит недопустимые значения или указывает цель, которую API отказывается запрашивать.
Тело, которое не является объектом или массивом JSON, считается некорректным JSON и возвращает Invalid JSON in request body, как показано ниже.
В Single, Proxy Finder и Browser отсутствующее поле, поле с неверным типом или значением вне диапазона указывается в сообщении как <field>: <reason>. Вложенные поля объединяются точками (validate.status.accept). Указывается до пяти проблем через разделитель ; , а любые последующие завершают сообщение как and <n> more:
{
"error": "Invalid request: url: Invalid input: expected string, received undefined"
}
Это client_error, и плата за него не взимается. Auto вместо этого сообщает о поле, которое не может принять, внутри HTTP 200, как описано ниже в разделе Reading Failures from /api/auto/.
Этот же статус 400 применяется для защиты от SSRF. Если ваш url резолвится в приватный, loopback или иной зарезервированный диапазон IP (RFC 5735, RFC 6598, зарезервированные блоки IPv6), request отклоняется до выхода из сети FourA:
{
"error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts."
}
<target> представляет собой адрес или имя хоста и адрес, в который оно разрешилось. URL, который не удается распарсить или который не является http:// либо https://, возвращает ту же ошибку 400.
Целевой адрес на собственном API-хосте FourA (eu.api.foura.ai или api.foura.ai) также возвращает 400 в режимах Single, Proxy Finder, Browser и Auto, еще до выполнения запроса или списания средств. Обычно это означает, что ссылка со страницы была разрешена относительно URL API, а не URL самой страницы:
{
"error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
<url> - это целевой URL в точности в том виде, в котором вы его отправили. Страница Inspect является единственным исключением: FourA все равно выполняет запрос к https://eu.api.foura.ai/inspect для вас.
URL, содержащий пробел или управляющий символ, также возвращает 400 на Single, Proxy Finder и Auto до отправки запроса и списания средств. Ссылка, скопированная со страницы как есть, часто содержит такие символы (javascript: void(0), ссылка для шеринга с пробелами в тексте). Кодируйте их, заменяя пробел на %20. Browser выполняет запрос к такому URL так же, как Chrome:
{
"error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
Имя хоста, которое не удается разрешить, не отклоняется сразу. Вызов возвращает HTTP 200 с status: 0 и причиной (could not resolve <host>: <reason>), и плата за него не взимается. Целевой ресурс, к которому обращается FourA, но не получает HTTP-ответа (исчерпан лимит перенаправлений, таймаут соединения или чтения, сброс соединения), также возвращает HTTP 200 с error и total_time без status: см. Request Outcomes.
На тарифе Single тело ответа размером более 128 МБ после декодирования прерывается. Вызов возвращает HTTP 200 с "error": "Response body exceeds the 128 MB limit" и не тарифицируется.
Некорректный JSON в теле запроса отклоняется аналогичным образом, до чтения каких-либо полей:
{
"error": "Invalid JSON in request body"
}
У полей proxy и ignoreProxies есть собственные ошибки 400. Оба принимают непрозрачные идентификаторы proxy ID из предыдущих ответов, поэтому любые другие значения декодировать не удастся:
| Сообщение | Причина |
|---|---|
Invalid proxy format |
Значение proxy не является proxy ID, выданным FourA. Прямой адрес proxy приводит к этой ошибке. |
Invalid ignoreProxies format |
Одно из значений в ignoreProxies не является proxy ID. |
Proxy not found |
Идентификатор успешно декодирован, но больше не указывает на активный выходной узел. Выберите новый узел. |
Managed exit: this proxy id cannot be pinned to a request |
Выходной узел существует, но FourA не удерживает его открытым для именованного запроса. ID премиум-узла вызывает эту ошибку, если в вашем тарифе закончился премиум-трафик. Используйте сессию, в которой он был получен, или выполните вызов через POST /api/proxy/ и используйте назначенный узел. |
Решение: проверьте, что запрос содержит все обязательные поля, URL использует http:// или https:// с пробелами в виде %20, хост разрешается в публичный адрес, а любое значение proxy представляет собой ID, скопированный точно из предыдущего ответа.
Это результаты категории client_error: запрос не покидал FourA, поэтому ресурсы вашего тарифа списаны не были.
401: Не авторизован
Ваш API key отсутствует или недействителен.
Отсутствует ключ:
{
"error": "Missing API key. Include X-API-Key header."
}
Недопустимый ключ:
{
"error": "Invalid API key"
}
Решение: убедитесь, что заголовок X-API-Key содержит действительный ключ. При необходимости сгенерируйте новый ключ в Dashboard.
Ошибка 401 всегда означает, что FourA проверил ваш ключ и отклонил его. Если FourA временно не может проверить ключ, возвращается 503 API key check temporarily unavailable (см. ниже), но не 401.
403: Не входит в ваш тарифный план
Запрос обратился к endpoint или параметру, который не включен в ваш тарифный план. В ответе устанавливается X-FourA-Limit, и этот же код передается в теле ответа в поле reason:
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
reason возвращает plan_limit_feature для endpoint, не входящего в тариф, или для exitCountries и полей exit location на тарифе без геотаргетинга, а также plan_limit_premium для exitClass: premium на тарифе без премиум-выходов, либо для exit location при исчерпании премиум-трафика. Строка error указывает конкретный endpoint или параметр.
Код 403 от FourA никогда не связан с целевым сайтом: обращения к нему не было. Ошибка 403, возвращенная целевым сайтом, приходит как HTTP 200 с status: 403 в теле ответа.
Решение: удалите параметр, вызовите endpoint, входящий в тариф, или обновите тариф. Заголовок Retry-After не задается, так как ожидание не изменит результат. Средства не списаны: статус выполнения rate_limit, а тарифицируется только success.
413: Слишком большой размер полезной нагрузки
Тело запроса JSON превышает допустимый для FourA размер (100 КБ). Ответ возвращается не в формате JSON и не содержит X-FourA-Request-Id, так как тело отклоняется до его прочтения.
Решение: отправьте data меньшего размера. Средства не списаны.
429: Превышен лимит запросов
Код 429 возвращают две разные проверки, и они содержат разные поля.
Собственные лимиты вашего тарифа. В ответе передается заголовок X-FourA-Limit с указанием лимита, отклонившего вызов, а в теле ответа тот же код дублируется в поле reason:
{
"error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
"reason": "plan_limit_concurrency",
"documentation": "https://foura.ai/prices",
"limit": 50,
"in_flight": 51,
"retry_after_seconds": 1
}
reason принимает одно из значений: plan_limit_concurrency, plan_limit_rate, plan_limit_browser_daily, plan_limit_credits или plan_limit_bandwidth. Если ожидание имеет смысл, время ожидания указывается в retry_after_seconds и в header Retry-After, но никогда в retryAfter. plan_limit_browser_daily не содержит ни того, ни другого, так как лимит восстанавливается в полночь по UTC, а не через секунды. Средства не списывались: результат rate_limit, а тарифицируется только success.
Общий лимит платформы. Заголовок X-FourA-Limit отсутствует, а время ожидания указано в retryAfter:
{
"error": "Rate limit exceeded",
"status": 429,
"service": "single",
"retryAfter": 5,
"current": { "concurrency": 12, "rpm": 3000 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
current и limits описывают состояние сервиса для всего трафика, а не для вашего аккаунта. Отказ здесь означает, что FourA перегружен.
Решение: Подождите время, указанное в Retry-After, retry_after_seconds или retryAfter из ответа. При ограничении параллелизма или rate limit ограничьте число открытых запросов вместо повторной отправки отклоненной пачки. При исчерпании дневного лимита или лимита расчетного периода остановите выполнение. См. Rate Limits с описанием всех полей и Параллельное выполнение запросов для знакомства с шаблоном.
500: Ошибка сервера
Что-то пошло не так на нашей стороне.
Решение: Повторите запрос через небольшую паузу. Если ошибка повторяется, проверьте страницу статуса или обратитесь в поддержку, указав X-FourA-Request-Id из неудавшегося ответа.
502: Вышестоящий сервис недоступен
FourA не смог получить ответ от собственного движка (Upstream unavailable: сбой соединения) или получил ответ, который не удалось прочитать (Malformed JSON from backend).
{
"error": "Upstream unavailable",
"details": "..."
}
Решение: Повторите запрос с небольшой задержкой (backoff). Ошибка произошла на нашей стороне, поэтому она бесплатна: результат service_error, а списывается только success.
504: Таймаут вышестоящего сервиса
Движок не уложился в лимит времени, выделенный на этот request.
{
"error": "Upstream timeout",
"details": "the backend did not finish inside the time budget for this request"
}
Ошибка 504 связана с длительностью выполнения задачи, а не с вашим ключом, параметрами или proxy. Обычные причины: медленные целевые ресурсы, решение проверок на холодную и тяжелые страницы.
Решение: увеличьте timeout_ms в request (Single принимает до 120000, Browser до 120000, Auto до 180000) или повторите попытку. FourA ожидает указанный вами лимит плюс небольшой запас, поэтому увеличение времени действительно дает дополнительное время на выполнение.
503: Сервис отключен или перегружен
Ошибка 503 означает, что сервис временно недоступен из-за технического обслуживания, либо исчерпан лимит параллельных запросов платформы. Оба варианта содержат одинаковые ключи: error, status, service, retryAfter, current и limits. Различайте их по значению строки error, а не по составу полей.
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
Service disabled означает техобслуживание, а current возвращает 0 для обоих счетчиков, так как request был отклонен до проведения измерений. Service at capacity представляет собой формат concurrency, и здесь current содержит реальную загрузку платформы. Структура описана в разделе Rate Limits.
Решение: Подождите retryAfter секунд, затем повторите попытку. На странице статуса указаны активные периоды обслуживания.
Третий вариант ответа 503 не содержит retryAfter. Это означает, что движок, обслуживающий ваш endpoint, не смог принять вызов: он перезапускался, произошел сбой на стороне FourA до выполнения вашего request или (для Browser) все браузеры оставались заняты в течение 10 секунд, отведенных на ожидание страницы. backend_status указывает собственный статус движка, а detail содержит начало его ответа:
{
"error": "Backend service unavailable",
"backend_status": 503,
"detail": "..."
}
Это service_error, и плата за него не списывается. Повторите запрос через пару секунд. Некорректный сам по себе request сюда не попадает: он получает 400 с указанием конкретного поля.
Четвертый 503 означает, что FourA временно не удалось проверить ваш API key, например, во время переключения базы данных. С вашим ключом все в порядке, и ничего не выполнялось. Ответ содержит Retry-After: 5 и аналогичное ожидание в retryAfter:
{
"error": "API key check temporarily unavailable",
"status": 503,
"retryAfter": 5
}
Плата не списывается. Повторите запрос через retryAfter секунд. Ключ, подтвержденный FourA за последние 10 минут, продолжает работать в такой момент, поэтому данный ответ встречается редко.
Чтение сбоев из /api/auto/
POST /api/auto/ отвечает с HTTP 200 каждый раз, когда ladder запускался, даже если каждый шаг завершился сбоем. Фактический результат находится в body:
{
"status": 403,
"error": "exit blocked by the target defense",
"attempts": 7,
"meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
status содержит последний статус, возвращенный целевым ресурсом, либо 502, если ни одна попытка до него не дошла (504, если сначала истек лимит времени). Каждый неудачный ответ от выполненного каскада попыток также содержит attemptReport с подсчетом ошибок попыток, однострочный summary, который безопасно логировать, а meta.attemptsByEngine и meta.browserRequests указывают, что именно отправлял вызов. См. раздел Why an Auto Call Failed. Поле запроса, которое Auto не может принять (например, timeout_ms меньше 5000 или больше 180000), возвращается точно так же: HTTP 200 с "status": 400 и причиной в error, до выполнения каких-либо попыток и совершенно бесплатно.
Поэтому не разветвляйте логику по транспортному статусу для Auto. Вместо этого читайте status и error из тела ответа. Настоящий non-200 статус от /api/auto/ означает, что FourA отклонил вызов до запуска каскада или не смог его завершить: 400 (некорректный JSON, приватный или зарезервированный целевой ресурс, либо адрес самого API FourA), 401, 413, 502, 503 или 504. Одно ограничение тарифного плана проверяется сразу: exitClass: premium на тарифе без премиум-точек выхода возвращает 403 с X-FourA-Limit: plan_limit_premium до выполнения какой-либо работы. Все остальные лимиты, ваши или платформы, возвращаются внутри ответа 200 со своим статусом в теле.
Если сайт завершил ошибкой несколько вызовов Auto подряд с вашим API-ключом, Auto некоторое время будет сразу отвечать на следующие вызовы к нему для этого ключа без попыток отправки: "error": "target temporarily unservable, retry later", "status": 503 и retryAfter в секундах. Это бесплатно; подождите retryAfter секунд.
Лимит тарифа, достигнутый одним из подвызовов, также возвращается как HTTP 200. Тело содержит сам отказ с его reason, а также status и meta, при этом ответ содержит тот же заголовок X-FourA-Limit, что и прямой отказ:
{
"status": 429,
"error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 75000,
"hard_stop": 75000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z",
"meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
Какие лимиты останавливают всю цепочку, а какие лишь закрывают отдельный шаг, описано в разделе Smart Fetch (Auto).
Сбои на стороне цели внутри 200 OK
Не каждый сбой возвращается в виде статуса HTTP, отличного от 2xx. Если цель отвечает HTTP 200, но ответ FourA содержит error (например, ваши правила validate отклонили тело ответа) или тело представляет собой страницу проверки, распознанную FourA, итогом будет application_error. Когда цель возвращает статус, отличный от 200, который не принимается вашими правилами validate, итогом будет application_fail, а тело ответа передается без изменений.
Ни один из этих случаев не тарифицируется: тарифицируется только success. Вызов Browser, при котором все браузеры заняты, ожидает освобождения до 10 секунд. Если ни один не освободился, возвращается 503 Backend service unavailable, описанный выше. Browser также может вернуть HTTP 200 с "error": "No available browser slot", если не удалось выделить браузер вовсе. Оба случая не тарифицируются. Повторите запрос через несколько секунд или держите меньше открытых вызовов Browser одновременно. Полная классификация приведена в справочнике Outcomes.
Вызов Single через закрепленный вами proxy также может вернуть HTTP 200 с кодом "error": "The exit gave the same answer for <n> different sites" рядом с телом ответа. FourA зафиксировал, что этот узел отдавал ту же страницу несвязанным сайтам, то есть страница принадлежит самому узлу, а не запрошенному ресурсу. Это считается application_error и не тарифицируется. Возьмите новый узел из POST /api/proxy/, который пропускает такие узлы автоматически.
То же самое применимо, когда вместо сайта отвечает собственная сеть выходного узла. Вызов возвращает "error": "The exit answered instead of the site (<name>)" или "error": "Corporate web gateway intercepted the request (<name>)" (страница входа, фильтрации или редирект на нее), "error": "The exit intercepted TLS and answered instead of the site (<name>)", когда узел ответил от имени самого сайта, или "error": "Honeypot echo proxy (plaintext request dump)", когда узел вернул копию вашего собственного запроса. FourA проверяет эти ситуации независимо от ваших правил validate, включая загрузки returnBuffer. Ни один из этих случаев не тарифицируется. Получите новый узел аналогичным образом.
Кодировка ответа
FourA автоматически декодирует тело ответа в UTF-8. Если цель отдает windows-1251, gbk, shift_jis, iso-8859-* или любую другую кодировку, указанную в заголовке Content-Type либо в теге HTML <meta charset>, вы получаете чистую строку UTF-8 в поле data (single, proxy) или body (browser).
Для бинарных данных (изображения, protobuf, аудиопотоки) укажите returnBuffer: true в запросе. В этом случае Single и Proxy возвращают data как объект с исходными байтами, {"type": "Buffer", "data": [<byte values>]}, без перекодирования набора символов.
Стратегия повторных попыток
Практическая политика повторных попыток:
import time
import requests
# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def make_request(url, payload, api_key, max_retries=3):
for attempt in range(max_retries):
resp = requests.post(
url,
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json=payload,
)
if resp.status_code == 200:
return resp.json()
body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
request_id = resp.headers.get("X-FourA-Request-Id", "?")
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")
# Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
header = resp.headers.get("Retry-After")
retry_after = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
)
if resp.status_code in (429, 503):
time.sleep(retry_after)
continue
if resp.status_code >= 500: # 500, 502, 503, 504 are all ours to fix
time.sleep(2 ** attempt)
continue
# 400/401/403/404 won't fix themselves
raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")
raise RuntimeError(f"Exhausted {max_retries} retries")
Сбои прокси содержат отчет
Вызов POST /api/proxy/, исчерпавший все попытки, возвращается как HTTP 200 с оболочкой ошибки (error envelope), а не как код ошибки HTTP. Строка ошибки короткая и всегда имеет одинаковую структуру, поэтому рядом с ней передается объект attemptReport со счетчиками:
{
"error": "Download maxTry limit reached",
"attemptReport": {
"total": 25,
"noResponse": 0,
"defense": 0,
"contentRejected": 25,
"statusRejected": 0,
"other": 0,
"vendors": [],
"profilesTried": ["default"],
"summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
},
"total": 34.812
}
Логируйте attemptReport.summary вместе с ошибкой, и вы поймете, были ли выходные узлы заблокированы, недоступны или возвращали страницы, которые отклонили ваши собственные правила validate. Справочник по полям и действия для каждого счетчика: Почему у proxy request закончились попытки.
Связанные разделы
- Rate Limits: лимиты тарифа, параллелизм и детали RPM
- Параллельное выполнение запросов: соблюдение лимита параллелизма вашего тарифа
- Результаты запросов: описание семи значений outcome
- Частые проблемы: симптомы, причины, решения
- Проверки сайтов: когда в теле ответа страница с проверкой вместо ошибки
- Почему у proxy request закончились попытки: чтение
attemptReport