# Response headers

> URL: https://foura.ai/ru/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

Каждый ответ 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](https://foura.ai/docs/api/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. Заголовок устанавливается даже при сбое аутентификации, поэтому вы можете сопоставлять и некорректно настроенные вызовы.

```bash
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](https://foura.ai/docs/dashboard/activity-log) для управляемых вами ключей, поэтому вы можете открыть соответствующую строку и изучить сохраненные request и response.

### Пример: логирование на вашей стороне

```python
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()
```

```javascript
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](https://foura.ai/docs/api/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](https://foura.ai/docs/dashboard/activity-log) для каждого вызова также показывает его.

## 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`, так как ожидание не изменит результат.

```python
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](https://foura.ai/docs/api/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](https://foura.ai/docs/dashboard/activity-log) и страница [Usage & Limits](https://foura.ai/docs/dashboard/quota) показывают фактический учет. Назначение `exitClass` и условия использования premium exit: [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

## X-FourA-Browser-Used-Today и X-FourA-Browser-Limit-Per-Day

Эти два header передают суточный лимит browser прямо в ответе. Это те же значения, что отображаются на странице [Usage & Limits](https://foura.ai/docs/dashboard/quota), поэтому их можно отслеживать без постоянных запросов к 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](https://foura.ai/docs/api/rate-limits).

В `POST /api/browser/` счетчик включает текущий запрос. В `POST /api/auto/` возвращается максимальное значение счетчика, зафиксированное во время работы лестницы попыток, поэтому оно может отставать от суточного расхода из-за других параллельно выполняемых запросов. Ответ Auto, не отправлявший запрос (например, при 120-секундной паузе после серии сбоев на целевом сайте), не содержит ни один из этих заголовков. Расход лимита за один вызов Auto указан в `meta.browserRequests`: см. [Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Поведение кэша

API не устанавливает `Cache-Control`. Ответ может содержать слабый `ETag`, вычисленный на основе его тела, но кэширование не выполняется: каждый вызов идет напрямую к бэкенду. Если вам требуется кэширование, реализуйте его на своей стороне.

## Заголовки ответа целевого сайта

Заголовки, возвращенные целевым сайтом, отсутствуют в HTTP-ответе FourA API. Они возвращаются внутри JSON-контейнера в поле `headers`. Для эндпоинтов Single и Proxy это массив объектов заголовков для каждого перехода (по одной записи на каждый шаг редиректа). Для эндпоинта Browser это плоский объект с заголовками финального ответа.

```json
{
  "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](https://foura.ai/docs/api/endpoints): структуры envelope для request и response
- [API Errors](https://foura.ai/docs/api/errors): структура ответов с ошибками
- [Request Outcomes](https://foura.ai/docs/api/outcomes): какие результаты тарифицируются
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): история по каждому request с ключом по request ID
- [Rate Limits](https://foura.ai/docs/api/rate-limits): что означает каждое значение `X-FourA-Limit`
