Response Headers

Всеки response от FourA API съдържа малък набор от персонализирани headers. Те са полезни за tracing, поддръжка, равняване на сметките и последващ анализ.

Headers, задавани от FourA

Header Задава се при Описание
X-FourA-Request-Id Всеки /api/* response, включително грешки и 401s, с изключение на body, което FourA изобщо не може да прочете (400 Invalid JSON in request body, 413), което се отхвърля преди присвояване на ID UUID, идентифициращ този request. Записвайте го в логовете от ваша страна.
X-FourA-Credits Всеки /api/* response, достигнал до backend-а Изразходвани кредити за това извикване. Връща се при успех и при грешка (работата е извършена и в двата случая).
X-FourA-Limit Всеки 403 или 429, предизвикан от някой от лимитите на вашия план Кой лимит е отхвърлил извикването: plan_limit_, последван от feature, premium, concurrency, rate, browser_daily, credits или bandwidth.
Retry-After 429 при лимит на плана, които изчакването изчиства (concurrency, rate, кредити, трафик), и 503 API key check temporarily unavailable Секунди за изчакване като цяло число. Съответства на retry_after_seconds в body при лимит на плана и на 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/ отговор, чийто ladder е изпратил request, който те не са отхвърлили Browser заявки, преброени днес за вашия акаунт: вижте по-долу.
X-FourA-Browser-Limit-Per-Day Същите отговори, когато планът ви задава дневен брой Browser заявки, разрешени от вашия план на ден.
X-FourA-Check-Page Single, Proxy Finder и Browser отговори, чието HTTP 200 body е страница за проверка за ботове или отказ, която FourA разпознава Името на страницата, например amazon-captcha. Такъв request не се таксува: вижте Request Outcomes.
Content-Type Всеки response Винаги application/json за обвивката. content-type на целта се връща в полето headers на обвивката.

X-FourA-Request-Id

Всяко извикване към POST /api/auto/, POST /api/single/, POST /api/proxy/ или POST /api/browser/ се маркира с UUID. Този header се задава дори при неуспешна автентикация, така че можете да проследявате и неправилно конфигурирани извиквания.

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 на заявката (request ID) и ние ще открием точния call в нашите записи.
  • Вашите собствени логове: съхранявайте го до реда в логовете на вашето приложение. Ако потребител съобщи, че "данните бяха грешни в 14:32", можете да направите replay на точния 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 limits на платформата никога не го задават, така че заглавката е най-бързият начин да разграничите "планът ми спря това" от "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)))

Седемте стойности и съответните полета в body са описани в Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class указва класа на изхода, доставил body: premium при премиум изход, standard при стандартния пул. Появява се при POST /api/proxy/ или POST /api/auto/ response, доставил страница, когато в request е посочен exitClass, като body носи същата стойност (exitClass при Proxy, meta.exitClass при Auto), както и при Single или Browser response, когато фиксираният proxy е бил премиум изход, където в body няма поле за това. При неуспешно извикване на Proxy или Auto не се връща нищо, затова то не съдържа нито header, нито полето.

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 изход се отчита както към вашия premium трафик, така и към общия ви bandwidth. Той се измерва в мрежата и включва premium опити, които не са върнали вашата страница, така че заявка, отговорена с standard, все още може да е използвала част от premium трафика при опит, неуспял преди отговора от стандартния пул. Този header посочва класа, който е доставил отговора, а не дали е използван premium трафик: маркировката premium на ред в Activity и страницата Usage & Limits показват какво е било отчетено. Какво прави exitClass и кога се използва premium изход: exitClass.

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

Тези два header-а съдържат вашия дневен лимит за браузър в самия отговор, същите стойности, които страницата Usage & Limits показва, за да можете да го проследявате без polling към таблото за управление.

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, изчислен от неговото тяло, но нищо не се кешира: всяко извикване достига до бекенда. Ако се нуждаете от кеширане, добавете го от ваша страна.

Хедъри на целевия отговор

Хедърите, върнати от целевия сайт, не присъстват в 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 на обвивката, а не от самия HTTP response на API извикването.

  • API Endpoints: Структури на request и response обвивките
  • API Errors: Как са структурирани отговорите за грешка
  • Request Outcomes: Кои резултати са платими
  • Activity Log: История за всяка заявка по request ID
  • Rate Limits: Какво означава всяка стойност на X-FourA-Limit
Обновено: 5 ноември 2026 г.