Nagłówki response

Każda odpowiedź z API FourA zawiera niewielki zestaw niestandardowych nagłówków. Są one przydatne do śledzenia, wsparcia technicznego, rozliczeń i analizy post-hoc.

Nagłówki ustawiane przez FourA

Header Ustawiany dla Opis
X-FourA-Request-Id Każda odpowiedź /api/*, w tym błędy i 401, z wyjątkiem treści, których FourA nie może w ogóle odczytać (400 Invalid JSON in request body, 413), odrzucanych przed przypisaniem identyfikatora UUID identyfikujący to żądanie. Zapisuj go w logach po swojej stronie.
X-FourA-Credits Każda odpowiedź /api/*, która dotarła do backendu Kredyty zużyte na to wywołanie. Zwracane zarówno przy sukcesie, jak i przy błędzie (praca została wykonana w obu przypadkach).
X-FourA-Limit Każdy błąd 403 lub 429 wywołany przez jeden z limitów Twojego planu Informacja, który limit odrzucił wywołanie: plan_limit_, a następnie feature, premium, concurrency, rate, browser_daily, credits lub bandwidth.
Retry-After Błędy 429 wynikające z limitów planu, które ustępują po odczekaniu (współbieżność, limit żądań, kredyty, przepustowość) oraz błąd 503 API key check temporarily unavailable Czas oczekiwania w sekundach jako liczba całkowita. Odpowiada wartości retry_after_seconds w treści odpowiedzi limitu planu oraz retryAfter przy błędzie 503.
X-FourA-Exit-Class Każde wywołanie /api/proxy/ lub /api/auto/, które wskazało exitClass i zwróciło stronę, oraz każde wywołanie Single lub Browser obsłużone przez węzeł wyjściowy premium premium lub standard: klasa węzła wyjściowego, który dostarczył treść. Nieudane wywołanie Proxy nie dostarczyło niczego i nie zawiera tego nagłówka.
X-FourA-Browser-Used-Today Każda odpowiedź POST /api/browser/, której nie odrzuciły limity Twojego planu, oraz każda odpowiedź POST /api/auto/, której sekwencja wysłała nieodrzucone żądanie Liczba żądań Browser zliczona dzisiaj na Twoim koncie: patrz poniżej.
X-FourA-Browser-Limit-Per-Day Te same odpowiedzi, gdy Twój plan określa limit dzienny Liczba żądań Browser dozwolona w Twoim planie na dzień.
X-FourA-Check-Page Odpowiedzi Single, Proxy Finder i Browser, których treść HTTP 200 jest stroną weryfikacji botów lub odmowy rozpoznawaną przez FourA Nazwa strony, na przykład amazon-captcha. Takie żądanie nie jest rozliczane: zobacz Request Outcomes.
Content-Type Każda odpowiedź Zawsze application/json dla koperty. Typ zawartości celu jest zwracany wewnątrz pola headers koperty.

X-FourA-Request-Id

Każde wywołanie POST /api/auto/, POST /api/single/, POST /api/proxy/ lub POST /api/browser/ jest oznaczane identyfikatorem UUID. Nagłówek jest ustawiany nawet wtedy, gdy uwierzytelnianie się nie powiedzie, dzięki czemu można korelować również błędnie skonfigurowane wywołania.

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

Kiedy tego używać

  • Zgłoszenia do pomocy technicznej: dołącz ID żądania, a znajdziemy dokładne wywołanie w naszych rejestrach.
  • Własne logi: zapisuj je obok linii logu aplikacji. Jeśli klient zgłosi, że "dane były nieprawidłowe o 14:32", możesz powtórzyć dokładnie to samo żądanie.
  • Śledzenie w panelu: ten sam identyfikator pojawia się w sekcji Dziennik aktywności dla kluczy, którymi zarządzasz, dzięki czemu możesz otworzyć odpowiedni wiersz i sprawdzić przechwycone żądanie oraz odpowiedź.

Przykład: logowanie po Twojej stronie

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 zgłasza koszt w kredytach za właśnie wykonane wywołanie. To licznik, a nie rachunek: nagłówek odzwierciedla wykonaną pracę niezależnie od wyniku. Warstwa rozliczeniowa panelu nalicza w ramach Twojego planu tylko wyniki podlegające opłatom (zobacz Request Outcomes, aby sprawdzić, które wyniki są płatne).

Tabela kosztów

Engine Podstawa Z unblocker
Single 1 2
Proxy 2 4
Browser 5 10 (gdy zabezpieczenie zostało rozwiązane)

/api/auto/ to jedno żądanie w Twoim panelu, z kosztem kredytów stanowiącym sumę wykonanych wewnętrznie podwywołań (pojedyncze odtworzenie na rozgrzanym celu może zamknąć się w 2; rozwiązanie na zimno na trudnej stronie może zużyć znacznie więcej). Wartość X-FourA-Credits w odpowiedzi auto odpowiada polu meta.credits w treści i śledzi pełny koszt sekwencji.

Dlaczego zarówno nagłówek, jak i pole w treści?

Nagłówek jest wygodny: możesz go odczytać przed sparsowaniem treści, zapisać w logach obok wiersza żądania lub zsumować dla wielu wywołań bez parsowania JSON. W trybie Auto pole meta.credits w treści zawiera tę samą liczbę. Treści Single, Proxy i Browser go nie zawierają, więc w tych odpowiedziach nagłówek jest jedynym miejscem do jego odczytania. Każdy wiersz wywołania w Activity również go pokazuje.

X-FourA-Limit

X-FourA-Limit pojawia się tylko wtedy, gdy jeden z limitów Twojego planu odrzucił wywołanie. Współdzielone limity rate limit platformy nigdy go nie ustawiają, więc nagłówek jest najszybszym sposobem na odróżnienie komunikatu "mój plan to zablokował" od "FourA jest zajęte" bez parsowania treści.

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

Dwie z siedmiu wartości są zwracane z kodem 403 zamiast 429: plan_limit_feature (endpoint lub parametr exitCountries nie wchodzi w skład Twojego planu) oraz plan_limit_premium (exitClass: premium nie wchodzi w skład Twojego planu). Żadna z nich nie ustawia nagłówka Retry-After, ponieważ odczekanie nie zmieni wyniku.

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

Siedem wartości oraz skojarzone z nimi pola treści opisano w sekcji Limity zapytań.

X-FourA-Exit-Class

Nagłówek X-FourA-Exit-Class określa klasę węzła wyjściowego, który zwrócił treść: premium w przypadku węzła premium, standard w przypadku puli standardowej. Pojawia się w odpowiedzi POST /api/proxy/ lub POST /api/auto/ zwracającej stronę, gdy request wskazywał exitClass (wtedy treść zawiera tę samą wartość: exitClass w Proxy, meta.exitClass w Auto), a także w odpowiedzi Single lub Browser, gdy przypięty proxy był węzłem premium (wtedy treść nie zawiera dedykowanego pola). Nieudane wywołanie Proxy lub Auto nie zwraca niczego, więc nie zawiera ani nagłówka, ani pola.

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

Ruch przez węzeł wyjściowy premium wlicza się do limitu ruchu premium oraz do całkowitej przepustowości. Jest mierzony na poziomie sieci i obejmuje próby premium, które nie zwróciły Twojej strony. Oznacza to, że request zakończony kodem standard mógł zużyć część ruchu premium podczas próby nieudanej przed udzieleniem odpowiedzi przez standardową pulę. Ten header wskazuje klasę, która dostarczyła odpowiedź, a nie fakt zużycia ruchu premium: oznaczenie premium w wierszu Activity oraz strona Usage & Limits pokazują, co zostało naliczone. Informacje o działaniu exitClass oraz momentach użycia węzła premium znajdziesz tutaj: exitClass.

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

Te dwa headery przekazują dzienny limit przeglądarki bezpośrednio w odpowiedzi (te same wartości, które wyświetla strona Usage & Limits), dzięki czemu możesz go monitorować bez odpytywania dashboardu.

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

Licznik zeruje się o północy UTC i obejmuje każdy klucz w Twoim planie, a nie tylko ten, który wykonał to wywołanie. Żądanie odrzucone przez limity Twojego planu nie zawiera żadnego z tych nagłówków: jego treść zawiera zamiast tego used_today i limit_per_day, patrz Rate Limits.

W POST /api/browser/ liczba ta uwzględnia żądanie, które właśnie odczytujesz. W POST /api/auto/ jest to najwyższa wartość przekazana sekwencji prób w trakcie jej działania, więc może być niższa niż bieżący stan dzienny ze względu na inne wciąż trwające żądania. Odpowiedź Auto, która nie wysłała żadnego żądania, na przykład podczas 120-sekundowej pauzy po powtarzających się błędach w danej witrynie, nie zawiera żadnego z tych nagłówków. Liczba jednostek pobrana z limitu przez jedno wywołanie Auto znajduje się w meta.browserRequests: patrz Smart Fetch.

Zachowanie pamięci podręcznej

API nie ustawia Cache-Control. Odpowiedź może zawierać słaby ETag obliczony z jej treści, ale nic nie jest buforowane: każde wywołanie trafia do backendu. Jeśli potrzebujesz buforowania, zaimplementuj je po swojej stronie.

Nagłówki odpowiedzi celu

Nagłówki zwrócone przez witrynę docelową nie znajdują się bezpośrednio w odpowiedzi FourA API. Są zwracane wewnątrz koperty JSON w polu headers. Dla endpointów Single i Proxy jest to tablica obiektów nagłówków dla każdego przeskoku (jeden wpis na każdy krok przekierowania). Dla endpointu Browser jest to płaski obiekt nagłówków ostatecznej odpowiedzi.

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

Jeśli potrzebujesz konkretnego nagłówka docelowego, odczytaj go z pola headers koperty, a nie z odpowiedzi HTTP samego wywołania API.

Aktualizacja: 5 listopada 2026