Результаты запросов
Каждый request к FourA API классифицируется строго по одному outcome, как и каждый туннель через proxy-порт. Outcome вычисляется один раз в конце вызова и записывается на учетные данные, с которых он был выполнен. Ваша панель управления, лента активности и биллинг считывают одно и то же поле.
Только success расходует кредиты. Премиум-трафик учитывается отдельно от кредитов и не зависит от outcome: см. Billing Implications.
Семь возможных outcome
Вот семь состояний, которыми может завершиться request. Туннель использует пять из них: см. Tunnels Use the Same Vocabulary ниже.
| Outcome | Уровень | Значение |
|---|---|---|
success |
н/д | Доставлен корректный response. Учитывается в тарифицируемой квоте. |
application_error |
target | Целевой ресурс вернул HTTP 200, но в теле содержалось поле ошибки, либо тело представляет собой проверку на ботов или страницу отказа, распознаваемую FourA. |
application_fail |
target | Целевой ресурс вернул статус, отличный от 200, который не был принят вашими правилами validate или для которого не был передан validate, либо не вернул response вовсе, включая невозможность разрешить имя хоста целевого ресурса. |
client_error |
caller | Request был отклонен до того, как покинул FourA. Неверные параметры, некорректное значение proxy, URL заблокирован защитой от SSRF. |
rate_limit |
FourA | Request был отклонен до выполнения: лимитом вашего тарифного плана (403 для endpoint или параметра, не входящего в тариф, 429 при исчерпании лимита) либо общим лимитом платформы по RPM или параллельным запросам. |
service_error |
FourA | Движок ответил серверной ошибкой, либо его тело не являлось валидным JSON. |
service_fail |
FourA | Сбой в собственной сети FourA: движок не ответил вовремя, соединение разорвалось или вы отключились. |
Колонка уровня показывает, на чьей стороне причина:
- Результаты target относятся к сайту, к которому вы обращались. Request успешно дошел до FourA, а FourA успешно связался с целевым ресурсом. Ошибку вернул сам целевой ресурс.
- Результаты caller означают, что request не мог выполниться. Исправьте структуру и параметры запроса.
- Результаты FourA означают сбой на нашей стороне. Повторите попытку и проверьте страницу статуса, если они сохраняются.
Целевой сайт, вернувший 403, это application_fail, а не client_error. Ваш вызов был сформирован корректно. Сайт просто ответил отказом.
Как выглядит неудачный вызов
Вызов, который дошел до FourA и выполнился, возвращается с кодом HTTP 200 независимо от того, что произошло дальше. Только отказ до выполнения запроса (400, 401, 403, 413, 429) или ошибка на стороне FourA (5xx) возвращают другой HTTP-статус. Таким образом, outcome считывается из тела ответа, а не из транспортного статуса.
| Тело | Что произошло | Результат |
|---|---|---|
status: 200, headers, data, нет error |
Страница успешно доставлена. | success |
status, отличный от 200, headers, data, нет error |
Целевой сервер ответил, и вы не передали validate. Ответ сервера находится в data. |
application_fail |
status, отличный от 200, headers, data и error |
Целевой сервер ответил, но ваши правила validate отклонили ответ, например Status 404 is not in accept list 200. |
application_fail |
status: 200, headers, data и error |
Целевой сервер вернул HTTP 200, но ваши правила validate отклонили ответ, например Data not in accept list ["product"]. |
application_error |
Только error и total_time, без status, без data |
Целевой сервер не вернул HTTP-ответ: исчерпан лимит перенаправлений (Number of redirects hit maximum amount), истекло время ожидания соединения или чтения, соединение было сброшено или ответ был пустым. Текст содержит собственную причину движка. |
application_fail |
status: 0 и error, ничего больше |
Не удалось разрешить имя хоста: could not resolve <host>: <reason>. Ни один движок не запускался, а в режиме Auto нет meta. Повторные попытки ничего не изменят, пока не обновится DNS. |
application_fail |
Цикл перенаправлений в соответствии с пятой строкой:
{
"error": "Number of redirects hit maximum amount",
"total_time": 0.808
}
В POST /api/proxy/ вызов, исчерпавший попытки, содержит error: Download maxTry limit reached и attemptReport со счетчиками (см. API Errors). В POST /api/auto/ лестница, которая выполнилась с ошибкой, содержит status, error, attempts, attemptReport с причинами и meta.rung со значением fail.
X-FourA-Credits сообщает о проделанной работе, в том числе при сбое. Биллинг учитывает только success, поэтому ни один из описанных выше неудачных ответов не тарифицируется.
Успех учитывает validate
Без validate API помечает request как success, только если целевой сервер возвращает HTTP 200.
С validate успешность определяется заданными вами правилами. Если указать API, что для данного request допустимы как 200, так и 403, то 403 возвращается как success. Тело ответа по-прежнему передается без изменений.
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://target.example/feed",
"validate": {
"status": { "accept": [200, 403] }
}
}'
В этом вызове ответ 403 считается как success и тарифицируется как один request. Ответ 500 считается как application_fail и не тарифицируется.
Та же логика применима к validate.headers и validate.data. Любой response, который движок принимает согласно вашим правилам, возвращается со статусом success независимо от HTTP status.
Один вариант ответа никогда не бывает success, с validate или без него: HTTP 200, тело которого является распознанной FourA страницей проверки на ботов, например задачей визуальной верификации, страницей с требованием запуска JavaScript в браузере или страницей отказа, которую сайт отдает с HTTP 200. Такой request получает статус application_error и не тарифицируется. Тело по-прежнему передается вам без изменений, а заголовок X-FourA-Check-Page указывает тип страницы.
Влияние на тарификацию
| Результат | Тарифицируется | Учитывается в лимите |
|---|---|---|
success |
Да | Да |
application_error |
Нет | Нет |
application_fail |
Нет | Нет |
client_error |
Нет | Нет |
rate_limit |
Нет | Нет |
service_error |
Нет | Нет |
service_fail |
Нет | Нет |
Тарифицируются только те запросы, которые успешно доставили запрошенные вами данные. Ошибки на стороне FourA, целевого ресурса или вашей стороне бесплатны.
В таблице описаны кредиты. Премиум трафик учитывается отдельно: request, задействовавший premium exit, учитывает переданный этой попыткой трафик при любом исходе, так как выходной узел был использован. Попытка, которая еще выполнялась в момент получения ответа от другого exit, немедленно останавливается, а переданный ею до этого момента трафик также идет в учет.
Стандартный трафик тоже не зависит от результата: на тарифе с лимитом пропускной способности трафик каждого request идет в зачет. Request, отклоненный одним из лимитов вашего тарифа, не расходует трафик.
Туннели используют те же термины
Туннель через proxy port также завершается одним из этих исходов, поэтому единый набор статусов применяется к обоим продуктам. Возможны только пять из семи исходов, так как два исхода target требуют, чтобы FourA проанализировал ответ цели, а ответом туннеля является ваш собственный зашифрованный трафик.
| Результат | Для туннеля это означает |
|---|---|
success |
Туннель открыт и успешно получен вашим инструментом. |
client_error |
FourA не может открыть этот туннель: приватный или зарезервированный адрес либо порт, который не обслуживается. |
rate_limit |
Достигнут один из лимитов вашего тарифа (одновременные туннели, число открытий туннелей в минуту, стандартный трафик за период, отсутствие премиум трафика) либо сам порт исчерпал емкость или частоту подключений. |
service_error |
У FourA не нашлось подходящего узла exit для вашего запроса. Обычно это временно. |
service_fail |
Не удалось связаться с целевым ресурсом ни через один exit, опробованный FourA: ошибка DNS, таймаут, отказ в соединении. |
application_error |
Для туннеля не применяется. |
application_fail |
Для туннеля не применяется. |
Отказ также сопровождается краткой причиной, и панель управления показывает ее в понятных вам терминах, а не внутренних наших. Опция, которую FourA не может выполнить, отклоняется ответом 400 прямо на уровне соединения и не создает записи, поэтому она вообще здесь не появляется.
| Причина на экране | Что исчерпано |
|---|---|
| port not in plan | Ваш тариф не включает этот proxy-порт |
| tunnels at once | Все разрешенные тарифом одновременные туннели уже использовались |
| openings per minute | Лимит открытий туннелей в минуту по вашему тарифу исчерпан |
| traffic used up | Трафик вашего тарифа на текущий период исчерпан |
| premium not available | Premium-трафик сейчас недоступен на вашем тарифе |
| port was full | Сам порт достиг лимита емкости или частоты открытий. Повторите попытку через минуту. |
| port not served | FourA не открывает туннели к этому порту |
| private address | Частные и зарезервированные адреса недоступны |
Параметры туннеля не тарифицируются в кредитах, так как у туннеля нет request, за который их можно списать. Вместо этого порт тарифицирует байты. См. раздел Как тарифицируется ваш план.
Анализ результатов в панели управления
Каждый request с вашим API-ключом отображается в ленте Activity со своим статусом outcome. Страницы Metrics и Overview агрегируют это же поле для круговых диаграмм и таймлайнов.
Фильтруя ленту Activity по outcome, можно выбрать конкретный endpoint (Auto, Single, Proxy Finder, Browser), чтобы проверить, не относится ли сбой к определенному сервису. Переключите поле Product на Proxy, и те же бейджи outcome отфильтруют ваши туннели.
Эвристика повторных попыток
Базовая политика повторов, привязанная к outcome:
| Outcome | Безопасен повтор? | Когда повторять |
|---|---|---|
success |
н/д | Ответ уже получен. |
application_error |
Иногда | Проверьте тело ошибки целевого ресурса. Некоторые ошибки временные, большинство нет. Если выставлен X-FourA-Check-Page, сайт вернул страницу проверки: отправьте URL в Auto, который воспринимает проверку как шаг для обхода, а не как финальный ответ. |
application_fail |
Иногда | Если целевой сайт ограничивает частоту запросов (rate limit), снизьте скорость. Если блокирует вас, переключитесь на endpoint Proxy или Browser. |
client_error |
Нет | Request завершится с той же ошибкой. Исправьте входные данные. |
rate_limit |
Зависит | Выдержите паузу, указанную в response: Retry-After, retry_after_seconds или retryAfter. При plan_limit_browser_daily остановите запросы до полуночи UTC; при plan_limit_credits или plan_limit_bandwidth подождите до resets_at; при plan_limit_feature или plan_limit_premium измените request. |
service_error |
Да | Короткая экспоненциальная задержка. |
service_fail |
Да | Так же, как service_error. |
Связанные разделы
- API Errors: ошибки на уровне HTTP-ответов
- Proxy Port: коды статуса, возвращаемые при отказе туннеля
- Rate Limits: причины срабатывания
rate_limitи два формата ответа - Metrics: детализация результатов запросов
- Activity Log: история результатов по каждому запросу