Nagłówki odpowiedzi (Response Headers)

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

Headers FourA Sets

X-FourA-Request-Id

Każde wywołanie do 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, co pozwala na korelację również błędnie skonfigurowanych wywołań.

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 request ID, a odnajdziemy dokładne wywołanie w naszych rejestrach.
• Własne logi: zapisuj go obok wpisu w logach aplikacji. Jeśli klient zgłosi, że „dane były błędne o 14:32”, możesz odtworzyć dokładnie to zapytanie.
• Śledzenie w panelu: ten sam ID pojawia się w sekcji Activity feed dla zarządzanych kluczy, więc możesz otworzyć powiązany wiersz i sprawdzić przechwycony request oraz response.

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 informuje o koszcie w kredytach dla wlasnie wykonanego wywolania. To licznik, a nie rachunek: naglowek odzwierciedla zasoby zuzyte na wykonanie zadania, niezaleznie od wyniku. Warstwa rozliczeniowa w panelu nalicza wzgledem planu wylacznie platne wyniki (zobacz Wyniki zadan, aby sprawdzic, ktore wyniki podlegaja oplatom).

Tabela kosztow

/api/auto/ to jedno zadanie w Twoim panelu, o koszcie kredytowym bedacym suma jego wewnetrznych podwywolan (pojedyncze ponowienie na rozgrzanym celu moze skonczyc sie na 2; rozwiazanie od zera na trudnej stronie moze zuzyc znacznie wiecej). Wartosc X-FourA-Credits w odpowiedzi auto jest rowna wartosci meta.credits w tresci i odzwierciedla calkowity koszt sciezki eskalacji.

Dlaczego zarowno naglowek, jak i pole w tresci?

Naglowek jest wygodny: mozesz go odczytac przed przetworzeniem tresci, zarejestrowac w logach obok linii zapytania lub zsumowac dla wielu wywolan bez parsowania JSON. Pole meta.credits w tresci odpowiedzi (Auto) lub metadane poszczegolnych silnikow (panele Single, Proxy, Browser) zawieraja te sama liczbe, ale dostepna wewnatrz struktury odpowiedzi.

X-FourA-Limit

X-FourA-Limit pojawia sie wylacznie wtedy, gdy jeden z limitow Twojego planu odrzucil wywolanie. Wspoldzielone rate limity platformy nigdy go nie ustawiaja, wiec ten naglowek to najszybszy sposob na odroznienie komunikatu "moj plan to zablokowal" od "FourA jest przeciazone" bez parsowania tresci.

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 zwracają kod 403 zamiast 429: plan_limit_feature (endpoint lub parametr exitCountries nie jest objęty Twoim planem) oraz plan_limit_premium (exitClass: premium nie jest objęty Twoim planem). Żadna z nich nie ustawia Retry-After, ponieważ oczekiwanie nie zmieni odpowiedzi.

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 powiązane z nimi pola body znajdują się w sekcji Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class określa klasę węzła wyjściowego (exit), który dostarczył body: premium, gdy użyto węzła premium, oraz standard, gdy użyto puli standardowej. Pojawia się w odpowiedzi POST /api/proxy/, która zwróciła stronę, za każdym razem, gdy request wskazywał exitClass (gdzie body zawiera tę samą wartość), a także w odpowiedzi Single lub Browser, gdy przypięty proxy był węzłem premium (gdzie body nie ma dedykowanego pola). Nieudane wywołanie Proxy niczego nie zwróciło, 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 Twojego limitu ruchu premium oraz całkowitej przepustowości. Jest mierzony na poziomie sieci i obejmuje próby premium, które nie zwróciły Twojej strony, więc request zakończony statusem standard mógł mimo to zużyć część transferu premium podczas próby zakończonej niepowodzeniem przed odpowiedzią ze standardowej puli. Ten header określa klasę, która obsłużyła request, a nie to, czy zużyto transfer premium: oznaczenie premium w wierszu Aktywność oraz strona Użycie i limity pokazują faktycznie naliczone wartości. Działanie exitClass oraz zasady używania węzłów premium: exitClass.

Zachowanie Cache

API nie ustawia nagłówków Cache-Control ani ETag w odpowiedziach. Każde wywołanie trafia bezpośrednio do backendu. Jeśli potrzebujesz cachowania, zaimplementuj je po swojej stronie.

Nagłówki odpowiedzi docelowej

Nagłówki zwrócone przez stronę docelową nie znajdują się bezpośrednio w odpowiedzi FourA API. Są zwracane wewnątrz obiektu JSON jako pole headers. Dla endpointów Single i Proxy jest to tablica obiektów nagłówków per-hop (po jednym wpisie dla każdego kroku przekierowania). Dla endpointu Browser jest to płaski obiekt zawierający nagłówki końcowej 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 w kopercie (envelope), a nie z samej odpowiedzi HTTP wywołania API.

Powiązane

• API Endpoints: Struktury kopert request i response
• API Errors: Jak są ustrukturyzowane odpowiedzi błędów
• Request Outcomes: Które wyniki podlegają opłatom
• Activity Log: Historia poszczególnych żądań według identyfikatora request ID
• Rate Limits: Co oznacza każda wartość X-FourA-Limit