Правила validate теперь определяют успех

Правила validate вашего запроса теперь определяют классификацию каждого результата. Объявите 403 допустимым, и полученный 403 будет считаться успешным, тарифицироваться как успешный и отображаться в ленте Activity вместе с кодами 200.

Это кажется мелочью. Но это меняет подход к оценке точности скрапинга в масштабе.

Как это работает

Каждый запрос к FourA получает один из семи результатов, определяющих биллинг и аналитику. Тарифицируется только success. Остальные разделяются по тому, на чьей стороне произошел сбой:

application_fail и application_error, если целевой сайт отклонил запрос или вернул тело ошибки
client_error, если отправленный вами запрос был некорректным
service_fail, service_error и rate_limit, если запрос был заблокирован на нашей стороне

До этого изменения успех означал только одно: HTTP 200. Код 403 всегда считался application_fail, даже если именно этот ответ вам и требовался. (Некоторые API со спортивными данными возвращают 403 для рынков с гео-ограничениями, и ваш код ожидает именно этот сигнал.)

Теперь решение принимает ваш блок validate. Запрос проверяет ваши правила во время выполнения. Если ответ им соответствует, результат классифицируется как success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/feed",
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 403] },
      "data": { "fail": ["captcha", "Access Denied"] }
    }
  }'

Это считает 200 и 403 допустимыми статус-кодами. Если тело ответа содержит маркер страницы верификации или строку отказа в доступе, запрос считается неудачным. Все остальное считается success.

Два правила, о которых нужно помнить:

Без validate поведение не меняется. Запросы без объявленной валидации по-прежнему тарифицируются только при HTTP 200. Вы подключаете это явно.
validate работает в обе стороны. Правила accept пропускают, правила fail отклоняют. Они комбинируются. Вы можете разрешить [200, 403] и при этом отклонить запрос, если тело содержит неподходящий контент.

Влияние

Это изменение важнее всего для команд, чьи целевые ресурсы возвращают полезные ответы со статусом отличным от 200.

Примеры из запросов, которые мы видим ежедневно:

Спортивные API, возвращающие 403 для рынков с гео-ограничениями (полезные данные, которые стоит фиксировать как успех)
Поисковые endpoint в e-commerce, возвращающие 404, когда товара нет в наличии (сигнал для вашего кода, а не сбой)
Стриминговые API и сервисы частичной отдачи контента, возвращающие 206

До этого обновления таким командам приходилось вести собственный учет поверх наших логов Activity. Они не могли полагаться на колонку outcome, потому что их определение успеха не совпадало с нашим. Тарификация происходила по показателю, который для них ничего не значил.

Теперь эта колонка отражает реальность. Вкладка Activity в вашей панели управления показывает то, что вы определили как успех, а не то, что предположили мы. Итоговые цифры в счетах совпадают с вашими собственными подсчетами (изменение действует только на новые данные, поэтому старые строки Activity сохраняют исходную классификацию).

Практический эффект для задач скрапинга: меньше шагов сверки между вашим пайплайном и нашим счетом. Если вы уже валидировали тело ответа постфактум, теперь этот контракт можно перенести в сам запрос и перестать поддерживать параллельный набор правил успеха/неудачи вне нашего API. Единое определение того, заслуживает ли запрос места в вашем датасете, вместо двух противоречащих друг другу.

При этом мы сохранили защиту от ошибок. Если вы не передаете блок validate, ничего не меняется. Классификатор возвращается к правилу "200 означает успех", поэтому запросы, работавшие вчера, работают точно так же сегодня.

Для продвинутых пользователей

validate принимает три набора правил, которые выполняются независимо: status, headers и data. Каждый принимает опциональные списки accept и fail.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/9876",
    "followRedirects": 5,
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 304] },
      "headers": { "accept": { "content-type": "application/json" } },
      "data": { "accept": ["\"price\":"], "fail": ["maintenance", "captcha"] }
    }
  }'

Для этого требуется:

Статус 200 или 304
Response указывает content type JSON
Body содержит поле price
Body не содержит сообщения о технических работах или страницы верификации

Если хотя бы одно правило не выполняется, результат будет application_fail. Если все проверки пройдены, это success. Классификатор работает прямо внутри request, поэтому вы экономите round trip, который потребовался бы на отдельный шаг валидации.

В сочетании с followRedirects: перейдите до пяти перенаправлений, затем проверьте финальный response. Подмена чистого URL на страницу верификации завершится понятной ошибкой вместо загрязнения вашего датасета.

Совет из опыта запуска наших собственных скрейперов: объявляйте шаблоны data.fail более строго. Статус 200 OK со страницей проверки внутри это самый частый скрытый сбой на защищенных сайтах. Считайте body главным источником истины, а не статус-код.

Полная схема и правила композиции каждого поля validate описаны в справочнике по request.

Что дальше

Мы работаем над расширенным набором правил: regex-сопоставлениями для data, предикатами на основе JSON-path и более гибкой проверкой header. Принцип остается прежним. Вы задаете критерии успешного ответа, а API гарантирует их соблюдение на всех этапах, от request до счета за использование.

Если скрейпер падает, это должно быть очевидно сразу. А когда он работает по правилам, которые вы написали сами, полученным данным можно действительно доверять.