Response headers
Каждый ответ API FourA содержит небольшой набор пользовательских заголовков. Они полезны для трассировки, обращения в поддержку, сверки счетов и последующего анализа.
Заголовки, которые задает FourA
| Header | Set on | Description |
|---|---|---|
X-FourA-Request-Id |
Каждый ответ /api/*, включая ошибки и 401, кроме тела, которое FourA вообще не может прочитать (400 Invalid JSON in request body, 413), отклоняемого до назначения ID |
UUID, идентифицирующий этот запрос. Логируйте его на своей стороне. |
X-FourA-Credits |
Каждый ответ /api/*, достигший бэкенда |
Кредиты, потраченные на этот вызов. Возвращается как при успехе, так и при сбое (работа была выполнена в обоих случаях). |
X-FourA-Limit |
Каждый 403 или 429, вызванный одним из лимитов вашего тарифного плана |
Лимит, отклонивший вызов: plan_limit_, за которым следует feature, premium, concurrency, rate, browser_daily, credits или bandwidth. |
Retry-After |
429 по лимитам плана, которые снимаются ожиданием (concurrency, rate, credits, bandwidth), и 503 API key check temporarily unavailable |
Время ожидания в секундах целым числом. Соответствует retry_after_seconds в теле ответа лимита плана и retryAfter в ответе 503. |
X-FourA-Exit-Class |
Каждый вызов /api/proxy/ или /api/auto/, в котором был указан exitClass и доставлена страница, а также каждый вызов Single или Browser, обслуженный через премиум-выход |
premium или standard: класс выхода, доставившего тело ответа. Неудачный вызов Proxy ничего не доставил и не содержит этого заголовка. |
X-FourA-Browser-Used-Today |
Каждый ответ POST /api/browser/, не отклоненный лимитами вашего плана, и каждый ответ POST /api/auto/, цепочка которого отправила неотклоненный запрос |
Количество Browser-запросов, учтенных сегодня в вашем аккаунте: смотрите ниже. |
X-FourA-Browser-Limit-Per-Day |
Те же ответы, если ваш план устанавливает дневной лимит | Количество Browser-запросов, разрешенных вашим планом в день. |
X-FourA-Check-Page |
Ответы Single, Proxy Finder и Browser, чье тело HTTP 200 представляет собой распознанную FourA страницу проверки на ботов или отказа в доступе | Имя страницы, например amazon-captcha. Такой запрос не тарифицируется: смотрите Request Outcomes. |
Content-Type |
Каждый ответ | Всегда application/json для конверта. Исходный content-type целевого ресурса возвращается внутри поля headers конверта. |
X-FourA-Request-Id
Каждый вызов POST /api/auto/, POST /api/single/, POST /api/proxy/ или POST /api/browser/ помечается с помощью UUID. Заголовок устанавливается даже при сбое аутентификации, поэтому вы можете сопоставлять и некорректно настроенные вызовы.
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
X-FourA-Credits: 2
Content-Type: application/json
...
Когда использовать
- Обращения в поддержку: укажите request ID, и мы сможем найти точный вызов в наших логах.
- Собственные логи: сохраняйте его рядом со строкой лога вашего приложения. Если в жалобе клиента сказано, что «в 14:32 данные были неверными», вы сможете повторить именно этот request.
- Трассировка в Dashboard: этот же ID отображается в Activity feed для управляемых вами ключей, поэтому вы можете открыть соответствующую строку и изучить сохраненные request и response.
Пример: логирование на вашей стороне
import logging
import requests
log = logging.getLogger(__name__)
def fetch(url, api_key):
resp = requests.post(
"https://eu.api.foura.ai/api/single/",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={"method": "GET", "url": url},
)
request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
credits = resp.headers.get("X-FourA-Credits", "0")
log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
resp.raise_for_status()
return resp.json()
async function fetchPage(url, apiKey) {
const resp = await fetch('https://eu.api.foura.ai/api/single/', {
method: 'POST',
headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
body: JSON.stringify({ method: 'GET', url })
});
const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
const credits = resp.headers.get('X-FourA-Credits') || '0';
console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);
return resp.json();
}
X-FourA-Credits
X-FourA-Credits сообщает стоимость только что выполненного вызова в кредитах. Это счетчик, а не счет на оплату: заголовок отражает затраты на работу независимо от результата. Биллинговый уровень панели управления списывает с вашего тарифного плана только оплачиваемые результаты (см. Request Outcomes для информации о том, какие результаты подлежат оплате).
Справочник стоимости
| Engine | Base | With unblocker |
|---|---|---|
| Single | 1 | 2 |
| Proxy | 2 | 4 |
| Browser | 5 | 10 (when a defense was solved) |
/api/auto/ отображается как один запрос в вашей панели управления, а стоимость в кредитах складывается из суммы внутренних подзапросов (один повтор на прогретой цели может стоить 2; холодный обход защиты на сложном сайте может потратить намного больше). Значение X-FourA-Credits в ответе auto совпадает с meta.credits в теле ответа и отслеживает полную стоимость всей цепочки.
Зачем нужен и заголовок, и поле в теле?
Заголовок удобен: его можно прочитать до парсинга тела ответа, записать в лог рядом со строкой запроса или суммировать по множеству вызовов без парсинга JSON. В режиме Auto поле meta.credits в теле ответа содержит то же самое число. Тела ответов Single, Proxy и Browser его не содержат, поэтому для этих ответов заголовок остается единственным местом для чтения значения. Строка Activity для каждого вызова также показывает его.
X-FourA-Limit
X-FourA-Limit появляется только тогда, когда вызов отклонен из-за одного из лимитов вашего тарифного плана. Общие rate limit платформы никогда не устанавливают этот заголовок, поэтому по нему быстрее всего отличить ситуацию "мой тарифный план заблокировал вызов" от "FourA сейчас перегружен" без парсинга тела ответа.
HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json
Два из семи значений возвращаются со статусом 403 вместо 429: plan_limit_feature (endpoint или параметр exitCountries не входит в ваш план) и plan_limit_premium (exitClass: premium не входит в ваш план). Ни один из них не задает Retry-After, так как ожидание не изменит результат.
STOP_ON = {
"plan_limit_feature", "plan_limit_premium",
"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}
resp = requests.post(url, headers=headers, json=payload)
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
stop_the_run(limit) # hours or days away, not seconds
elif limit:
time.sleep(int(resp.headers.get("Retry-After", 1)))
Все семь значений и соответствующие поля тела ответа описаны в Rate Limits.
X-FourA-Exit-Class
X-FourA-Exit-Class указывает класс exit node, доставившего тело: premium для премиум-узла, standard для стандартного пула. Он присутствует в ответе POST /api/proxy/ или POST /api/auto/ с телом страницы, если в запросе был указан exitClass, при этом тело содержит то же значение (exitClass для Proxy, meta.exitClass для Auto). В ответах Single или Browser он появляется, когда закрепленный proxy являлся премиум-узлом (в теле ответа это поле отсутствует). Неудачный вызов Proxy или Auto ничего не возвращает, поэтому не содержит ни заголовка, ни поля.
HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
Трафик через premium exit учитывается как в расходе premium-трафика, так и в общем объеме bandwidth. Он измеряется на уровне сети и включает неуспешные premium-попытки, поэтому request с ответом standard все равно мог израсходовать часть premium-трафика, если попытка завершилась сбоем до ответа из standard pool. Этот header указывает класс, выполнивший доставку, а не сам факт использования premium-трафика: отметка premium в строке Activity и страница Usage & Limits показывают фактический учет. Назначение exitClass и условия использования premium exit: exitClass.
X-FourA-Browser-Used-Today и X-FourA-Browser-Limit-Per-Day
Эти два header передают суточный лимит browser прямо в ответе. Это те же значения, что отображаются на странице Usage & Limits, поэтому их можно отслеживать без постоянных запросов к dashboard.
HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
Подсчет сбрасывается в полночь по UTC и охватывает все ключи вашего тарифа, а не только тот, с которого был сделан вызов. Запрос, отклоненный лимитами вашего тарифа, не содержит ни один из этих заголовков: вместо этого его тело содержит used_today и limit_per_day, см. Rate Limits.
В POST /api/browser/ счетчик включает текущий запрос. В POST /api/auto/ возвращается максимальное значение счетчика, зафиксированное во время работы лестницы попыток, поэтому оно может отставать от суточного расхода из-за других параллельно выполняемых запросов. Ответ Auto, не отправлявший запрос (например, при 120-секундной паузе после серии сбоев на целевом сайте), не содержит ни один из этих заголовков. Расход лимита за один вызов Auto указан в meta.browserRequests: см. Smart Fetch.
Поведение кэша
API не устанавливает Cache-Control. Ответ может содержать слабый ETag, вычисленный на основе его тела, но кэширование не выполняется: каждый вызов идет напрямую к бэкенду. Если вам требуется кэширование, реализуйте его на своей стороне.
Заголовки ответа целевого сайта
Заголовки, возвращенные целевым сайтом, отсутствуют в HTTP-ответе FourA API. Они возвращаются внутри JSON-контейнера в поле headers. Для эндпоинтов Single и Proxy это массив объектов заголовков для каждого перехода (по одной записи на каждый шаг редиректа). Для эндпоинта Browser это плоский объект с заголовками финального ответа.
{
"status": 200,
"headers": [
{ "Content-Type": "text/html; charset=utf-8", "Server": "..." }
],
"data": "<!doctype html>...",
"total_time": 0.42
}
Если вам нужен конкретный целевой header, читайте его из поля headers конверта (envelope), а не из HTTP response самого вызова API.
Связанные разделы
- API Endpoints: структуры envelope для request и response
- API Errors: структура ответов с ошибками
- Request Outcomes: какие результаты тарифицируются
- Activity Log: история по каждому request с ключом по request ID
- Rate Limits: что означает каждое значение
X-FourA-Limit