Частые проблемы
Решения наиболее распространенных проблем при использовании FourA API.
Пустой или неполный контент
Симптом: API возвращает статус 200, но поле data пусто или не содержит ожидаемого контента.
Причина: целевая страница использует JavaScript для рендеринга контента после начальной загрузки страницы.
Решение: переключитесь с одиночного endpoint на browser endpoint. Используйте checkText, чтобы убедиться, что контент загрузился:
curl -X POST https://eu.api.foura.ai/api/browser/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/products",
"timeout_ms": 15000,
"checkText": "product-list"
}'
Примечание: browser endpoint возвращает контент в поле body (а не data).
403 Forbidden или страницы верификации
Симптом: API возвращает HTML, содержащий страницу верификации или сообщение об отказе в доступе.
Причина: целевой сайт распознал запрос как автоматический и заблокировал его.
Решение: используйте proxy endpoint для автоматической ротации IP:
curl -X POST https://eu.api.foura.ai/api/proxy/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"maxTries": 5,
"request": {
"method": "GET",
"url": "https://example.com/prices",
"unblocker": true
}
}'
Если проблема сохраняется, увеличьте maxTries, чтобы дать ротации proxy больше попыток.
Статус 403, возвращенный целевым ресурсом, приходит как HTTP 200 с status: 403 внутри тела ответа. Ошибка 403 самого вызова с заголовком X-FourA-Limit означает другое: см. 403 Not in Your Plan.
Ошибки таймаута
Симптом: запросы завершаются с ошибкой таймаута.
Причина: целевая страница загружается дольше настроенного таймаута.
Решение: увеличьте timeout_ms (по умолчанию 15s для single, 30s для browser, 45s для proxy):
curl -X POST https://eu.api.foura.ai/api/browser/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://slow-site.com",
"timeout_ms": 60000
}'
Для browser request также убедитесь, что значение checkText действительно присутствует на странице. Опечатка приведет к ошибке вызова с checkText:<your text> not found.
403 Не входит в ваш тариф
Симптом: API возвращает 403 с header X-FourA-Limit и reason со значением plan_limit_feature или plan_limit_premium.
{
"error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
Причина: ваш тарифный план не включает вызванный endpoint или переданный параметр. plan_limit_feature относится к недоступному endpoint, а также к exitCountries, exitState, exitCity, exitAsn или exitOs без геотаргетинга. plan_limit_premium относится к exitClass: premium без премиум-выходов, а также к Proxy-запросу с указанием exit location после исчерпания премиум-трафика. Целевой ресурс не опрашивался, списаний не произошло.
Решение: удалите параметр, вызовите endpoint, входящий в ваш план, или повысьте тариф. Вкладка Limits & Features в Usage & Limits содержит список доступных возможностей. Не повторяйте неизмененный запрос: заголовок Retry-After отсутствует, так как ожидание не изменит результат.
429 Слишком много запросов
Симптом: API возвращает 429.
Причина: запрос отклонен одной из двух проверок, и в ответе указано, какой именно. Если присутствует заголовок X-FourA-Limit, достигнут один из лимитов вашего плана: число одновременных запросов или запросов в минуту для данного endpoint, число Browser-запросов за день, либо кредиты или пропускная способность за расчетный период. Если заголовок отсутствует, исчерпан общий минутный лимит платформы для этого сервиса, что связано с общей нагрузкой FourA, а не с вашей.
Решение: сначала проверьте X-FourA-Limit. Подождите, если до сброса лимита осталось несколько секунд, или остановите запросы, если это не так. Лимиты плана, которые сбрасываются со временем, передают секунды в заголовке Retry-After и в retry_after_seconds; общий лимит передает их в retryAfter:
import time
import requests
# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}
def make_request(endpoint_url, payload, retries=3):
for i in range(retries):
resp = requests.post(
endpoint_url,
headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json=payload
)
if resp.status_code == 429:
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
header = resp.headers.get("Retry-After")
body = resp.json()
wait = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
)
time.sleep(wait)
continue
return resp
raise Exception("Rate limit not resolved after retries")
# Example: single request
make_request(
"https://eu.api.foura.ai/api/single/",
{"method": "GET", "url": "https://example.com"}
)
Если в заголовке указано plan_limit_concurrency или plan_limit_rate, решение заключается в ограничении числа одновременно открытых вызовов и числа запусков в минуту, а не в повторных попытках. Повторная отправка отклоненного пакета сразу же приведет к повторному отклонению всего пакета. Отклоненные вызовы не учитываются в лимите в минуту, но если они продолжают поступать со скоростью, превышающей этот лимит более чем в два раза, отклонения переходят в режим ожидания: тело ответа 429 содержит cooldown: true и предписывает сделать паузу на 30 секунд (retry_after_seconds: 30). В разделе Run Requests in Parallel описан нужный паттерн, а в подразделе Usage & Limits в Dashboard отображаются текущие счетчики рядом с вашими лимитами.
503 Сервис недоступен
Симптом: API возвращает статус 503.
Причина: Это происходит в трех случаях:
- Сервис перегружен. FourA уже выполняет предельно допустимое число одновременных запросов на данном движке для всего суммарного трафика, а не только вашего. Значение
Service at capacityв полеerror. Обычно это проходит за несколько секунд. - Сервис временно отключен. Проводятся технические работы. Значение
Service disabledв полеerror. - FourA временно не может проверить ваш ключ. Значение
API key check temporarily unavailableв полеerrorсRetry-After: 5. С вашим ключом все в порядке.
Во всех трех случаях ответ содержит поле retryAfter. Ни один из них не связан с ограничениями тарифа: лимиты вашего тарифа всегда возвращаются с заголовком X-FourA-Limit при статусах 403 или 429, но никогда при 503.
Решение: Подождите указанное количество секунд (retryAfter), затем повторите попытку:
import time
import requests
def make_request_with_retry(endpoint_url, payload, retries=3):
for i in range(retries):
resp = requests.post(
endpoint_url,
headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json=payload
)
if resp.status_code in (429, 503):
header = resp.headers.get("Retry-After")
body = resp.json()
wait = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
)
time.sleep(wait)
continue
return resp
raise Exception("Request not resolved after retries")
Ошибка 503 при превышении емкости означает, что FourA перегружен, поэтому единственное решение, снизить нагрузку и повторить попытку. Если же вы получаете отказ с кодом 429 и X-FourA-Limit, проблема на вашей стороне: уменьшите количество параллельных запросов в вашем пайплайне.
504 Время ожидания вышестоящего сервера истекло
Симптом: API возвращает 504 с {"error": "Upstream timeout"}.
Причина: Обработка не завершилась в рамках бюджета времени, заданного для запроса. Причиной могут быть медленный целевой сайт, холодный запуск решения проверки или очень тяжелая страница. Это не связано с вашим ключом, параметрами или proxy.
Решение: Выделите запросу больше времени или повторите попытку. FourA ожидает указанный вами timeout_ms с небольшим запасом, поэтому его увеличение действительно продлевает время ожидания:
{
"url": "https://slow-site.com/report",
"timeout_ms": 90000
}
Для /api/auto/ на защищенном целевом ресурсе первый холодный вызов может занять десятки секунд. Его timeout_ms охватывает всю цепочку и принимает значения до 180000.
Когда у самого /api/auto/ заканчивается этот лимит, вызов все равно возвращает HTTP 200. Тело содержит error, начинающийся с time budget exhausted, а status обычно равен 504 (предыдущая неудавшаяся попытка может оставить там свой собственный статус). Увеличьте timeout_ms или повторите попытку.
502 Upstream недоступен
Симптом: API возвращает 502 с {"error": "Upstream unavailable"} или 503 с {"error": "Backend service unavailable"}.
Причина: FourA не удалось связаться со своим движком (Upstream unavailable), либо движок не вернул пригодный ответ (Backend service unavailable), обычно из-за перезапуска инстанса. В /api/browser/ страница ожидает свободный браузер до 10 секунд, если все заняты, и страница, продолжающая ждать после этого, возвращается как эта ошибка 503.
Решение: Повторите запрос с небольшой задержкой (backoff). Оба случая классифицируются как service_error, а тарифицируется только success, поэтому повторный запрос ничего не стоит. Если это продолжается дольше пары минут, проверьте страницу статуса.
401 Ошибки аутентификации
Симптом: Каждый запрос возвращает 401 Unauthorized.
Чек-лист:
- Убедитесь, что заголовок указан как
X-API-Key: YOUR_API_KEY(а неAuthorization: BearerилиApi-Key) - Проверьте API key на наличие лишних пробелов или символов перевода строки
- Создайте новый ключ в Dashboard, если текущий мог быть скомпрометирован
400 Некорректный запрос
Симптом: Вызов POST /api/single/, /api/proxy/ или /api/browser/ возвращает 400 с {"error": "Invalid request: <field>: <reason>; ..."}.
Причина: Поле в теле вашего запроса отсутствует, имеет неверный тип или выходит за допустимые пределы. В сообщении перечисляются неподдерживаемые поля и причины отказа (до пяти полей), после чего следует and N more, если есть другие ошибки. Запрос к целевому ресурсу не выполнялся, результат client_error, кредиты не списываются.
Решение: Исправьте указанные поля и отправьте запрос снова. То же самое тело запроса вызовет такую же ошибку 400, поэтому не повторяйте его без изменений. Справочник endpoint reference содержит список всех полей с их типами и ограничениями. В /api/auto/ та же ошибка возвращается как HTTP 200 с status: 400 и причиной в error.
400 Целевой ресурс резолвится в приватный или зарезервированный IP
Симптом: API возвращает 400 с Refusing to fetch <target>: target resolves to a private or reserved IP range до того, как запрос покидает FourA.
Причина: Ваш url разрешается в приватный, loopback или зарезервированный диапазон IP (RFC 5735, RFC 6598 или зарезервированные блоки IPv6). FourA отклоняет такие цели, чтобы ее сеть нельзя было использовать для доступа к внутренним хостам.
Решение: Запрашивайте публичный URL. При тестировании используйте публичную цель, например https://example.com или https://httpbin.org/get. Если целевой ресурс является вашим сервисом, сначала опубликуйте его на публичном хостнейме.
{ "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." }
Имя хоста, которое не удается разрешить, не отклоняется. Вызов возвращает HTTP 200 с status: 0 и причиной (could not resolve <host>: <reason>), как и любая цель, до которой FourA не может добраться, и он не тарифицируется.
400 Пробел в URL
Симптом: Single, Proxy или Auto возвращает 400 с invalid URL: it contains a space; encode it as %20 (the URL as sent: "...") до того, как запрос покидает FourA.
Причина: URL содержит пробел или управляющий символ, обычно это ссылка, взятая со страницы в исходном виде (javascript: void(0), ссылка для шеринга с текстом). Данные не загружаются, результат client_error, и кредиты не списываются.
Решение: Кодируйте URL перед отправкой (пробел заменяется на %20) и пропускайте ссылки, которые не ведут на страницы, например javascript:. Браузер загружает такие URL так же, как Chrome.
400 Целью является сам API FourA
Симптом: API возвращает 400 с Refusing to fetch <url>: that is the FourA API itself, not a page. до того, как запрос покидает FourA.
Причина: Ваш url указывает на api.foura.ai или eu.api.foura.ai. Краулер обычно делает это, когда разрешает относительную ссылку со страницы относительно URL API вместо собственного URL страницы, поэтому /category/news/ превращается в https://eu.api.foura.ai/category/news/. Ничего не загружается, и кредиты не списываются.
Решение: Разрешайте каждую ссылку относительно URL исходной страницы перед отправкой, например с помощью urljoin(page_url, href) в Python. Inspect endpoint (/inspect) это единственный адрес на хосте API, который можно запросить через FourA.
no_eligible_proxy при использовании exitCountries
Симптом: Вызов /api/proxy/ с exitCountries возвращает HTTP 200 с конвертом ошибки JSON:
{
"error": "No eligible proxy found for exit countries: CZ, GB",
"code": "no_eligible_proxy",
"details": { "exitCountries": ["CZ", "GB"] },
"total": 0.084
}
Причина: в текущем пуле proxy нет работающей точки выхода, видимая целевому сервису страна которой соответствует вашему разрешенному списку. Стандартный пул никогда не переключается на незапрошенную страну, если задан exitCountries. Без exitCountries в такой же ситуации возвращается {"error": "Failed"}: у FourA не было точки выхода для попытки, поэтому повторите запрос через несколько секунд.
Запрос, в котором указано местоположение точки выхода (exitState, exitCity, exitAsn, exitOs или exitLifetimeMin, вместе с exitClass: premium), отправляется только через premium-выходы. Когда у FourA не остается premium-выходов для выполнения запроса, вызов завершается с "error": "No premium exit answered for this request" и тем же code: no_eligible_proxy.
Решение: сохраните запрошенную область и повторите попытку позже. Пул обновляется примерно каждые десять минут, поэтому страна, для которой сейчас нет совпадений, часто появляется в течение часа.
import time, requests
def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
for _ in range(max_attempts):
r = requests.post("https://eu.api.foura.ai/api/proxy/",
headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={"maxTries": 5, "exitCountries": countries,
"request": {"method": "GET", "url": url}}).json()
if r.get("code") == "no_eligible_proxy":
time.sleep(wait_sec)
continue
return r
raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
Расширяйте список стран только в том случае, если требования вашего рабочего процесса к геолокации действительно изменились. Неявные переключения на другие страны могут нарушить работу зависимой логики дальше по цепочке.
Профиль браузера отклонен
Симптом: вызов возвращает unknown profile '<id>', no profile matches browser=... или browser profile selection requires unblocker:true.
Причина: переданные profile, browser, os или version отсутствуют в каталоге, либо передан профиль с unblocker: false.
Решение: обратитесь к GET /api/profiles для получения актуального каталога, выберите профиль из него и оставляйте unblocker включенным при выборе браузера.
Тело ответа возвращается в виде нечитаемого текста
Симптом: data (или body) ответа содержит кракозябры или нечитаемые символы, если целевой ресурс использует кодировку, отличную от UTF-8.
Причина: по умолчанию FourA автоматически декодирует тело ответа в UTF-8 на основе заголовка Content-Type целевого ресурса или тега HTML <meta charset>. Если целевой ресурс указывает неверную кодировку, текст искажается.
Решение: для бинарных полезных нагрузок (изображения, protobuf, необработанное аудио) укажите returnBuffer: true в запросе. В этом случае Single и Proxy вернут data как объект с исходными байтами ({"type": "Buffer", "data": [<byte values>]}) без перекодирования набора символов.
{
"method": "GET",
"url": "https://example.com/image.png",
"returnBuffer": true
}
Для текстовых ресурсов с неверно указанной кодировкой декодируйте необработанные байты вручную: выполните запрос с returnBuffer: true, прочитайте значения байтов в data.data, затем декодируйте их с правильной кодировкой.
Неожиданный HTML вместо JSON
Симптом: Ожидался JSON от целевого сайта, но получен HTML.
Причина: Целевая страница может отдавать разный контент в зависимости от заголовков.
Решение: Добавьте заголовок Accept и включите unblocker для реалистичных заголовков браузера:
curl -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://api.example.com/data",
"headers": [["Accept", "application/json"]],
"unblocker": true
}'
Вы также можете установить tryJsonData в true, чтобы FourA автоматически разбирал JSON-ответы.
Тело ответа содержит страницу проверки, а не контент
Симптом: Вызов прошел успешно, status равен 200, но data (или body) содержит проверку на бота вместо нужной страницы.
Причина: Целевой ресурс запустил проверку на бота, которую FourA обнаружил, но не смог пройти. В ответе это указано: Single и Proxy возвращают defense со значением solved: false, а Browser возвращает defenseSolved: false с указанием поставщика в defenses.present.
Решение: Сначала проверьте defense.vendor, затем повышайте уровень обработки. Попробуйте другой профиль браузера в Single, перейдите на Proxy для смены выходного узла или используйте Browser для выполнения JavaScript. Полный справочник полей и список поставщиков: Проверки сайтов.
Добавьте подстроку validate.data.accept, которая присутствует только на настоящей странице. Страница проверки, распознанная FourA, никогда не считается успехом: она возвращается с заголовком X-FourA-Check-Page и не тарифицируется. Без validate нераспознанная FourA страница проверки, возвращенная с кодом HTTP 200, будет считаться успешной, и вы узнаете об этом позже в пайплайне, а не в момент вызова.
Проблема не решилась?
Если ни одно из решений выше не помогло:
- Проверьте страницу статуса на наличие текущих инцидентов
- Проверьте метрики ваших запросов в Dashboard
- Обратитесь в службу поддержки по адресу support@foura.ai с деталями запроса (укажите
X-FourA-Request-Idиз неудавшегося ответа)
Следующие шаги
- Обработка ошибок: справочник кодов ошибок API
- Лимиты запросов: все лимиты тарифных планов и платформы с описанием полей
- Результаты запросов: как результаты классифицируют произошедшее
- Проверки сайтов: о чем говорит поле
defense - Выбор подходящего endpoint: подберите оптимальный подход для вашего целевого ресурса
- Обзор Dashboard: мониторинг ваших запросов