Заголовки ответа

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

Заголовки, которые устанавливает FourA

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
...

Когда его использовать

• Тикеты в поддержку: укажите ID запроса, и мы сможем найти точный вызов в наших записях.
• Ваши собственные логи: сохраняйте его рядом со строкой лога вашего приложения. Если жалоба клиента гласит: "данные были неверны в 14:32", вы можете воспроизвести точный запрос.
• Трассировка в панели управления: тот же ID появляется в ленте Activity для ключей, которыми вы управляете, поэтому вы можете открыть соответствующую строку и изучить перехваченные запрос и ответ.

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

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 для информации о том, какие результаты тарифицируются).

Справочник стоимости

/api/auto/ не добавляет отдельную тарифицируемую строку. Его стоимость в кредитах представляет собой сумму подвызовов, которые он сделал внутренне (один повтор на теплой цели может завершиться на 2, холодное прохождение на сложном сайте может потратить гораздо больше). Значение X-FourA-Credits в ответе auto равно meta.credits в теле и отслеживает полную стоимость цепочки.

Зачем и заголовок, и поле в теле?

Заголовок удобен: вы можете прочитать его перед парсингом тела, логировать рядом со строкой запроса или суммировать по многим вызовам без парсинга JSON. meta.credits (Auto) тела или метаданные по каждому движку (панели Single, Proxy, Browser) содержат то же число, но доступны для чтения внутри конверта ответа.

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

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

Заголовки ответа цели

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

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

Если вам нужен конкретный заголовок цели, прочитайте его из поля headers конверта, а не из HTTP-ответа самого вызова API.

Связанные

• API Endpoints: Форматы конвертов запроса и ответа
• API Errors: Как структурированы ответы с ошибками
• Request Outcomes: Какие результаты тарифицируются
• Activity Log: История по каждому запросу с ключом по ID запроса