Nagłówki odpowiedzi (Response Headers)

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

Nagłówki ustawiane przez FourA

X-Foura-Request-Id

Każde wywołanie do POST /api/auto/, POST /api/single/, POST /api/proxy/ lub POST /api/browser/ jest oznaczone UUID. Nagłówek jest ustawiany nawet wtedy, gdy uwierzytelnianie zawiedzie, więc możesz 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 wsparcia (support tickets): dołącz ID żądania, a będziemy mogli znaleźć dokładnie to wywołanie w naszych rejestrach.
• Własne logi: przechowuj to obok linii logu z aplikacji. Jeśli klient zgłosi, że "dane były błędne o 14:32", możesz odtworzyć dokładne żądanie.
• Śledzenie w panelu (dashboard tracing): to samo ID pojawia się w sekcji Activity feed dla zarządzanych kluczy, co pozwala otworzyć pasujący wiersz i zbadać przechwycone żądanie i 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 raportuje koszt kredytów za właśnie wykonane wywołanie. To jest licznik, nie rachunek: nagłówek odzwierciedla to, co praca pochłonęła, niezależnie od wyniku. Warstwa bilingowa panelu zlicza do twojego planu tylko wyniki podlegające opłacie (zobacz Request Outcomes, aby sprawdzić, które wyniki są płatne).

Cennik referencyjny

/api/auto/ nie dodaje osobnego wiersza rozliczeniowego. Jego koszt w kredytach to suma podwywołań wykonanych wewnętrznie (pojedyncze powtórzenie na rozgrzanym celu może skończyć się na 2; zimne rozwiązanie na trudnej stronie może kosztować znacznie więcej). Wartość X-FourA-Credits w odpowiedzi automatycznej równa się meta.credits w ciele i śledzi pełny koszt tej drabiny.

Dlaczego zarówno nagłówek, jak i pole w body?

Nagłówek jest wygodny: możesz go odczytać przed parsowaniem ciała odpowiedzi, zalogować obok linii żądania lub zsumować przez wiele wywołań bez parsowania JSON. meta.credits w ciele (dla Auto) lub metadane dla poszczególnych silników (panele Single, Proxy, Browser) przechowują tę samą liczbę, ale w czytelny sposób wewnątrz koperty z odpowiedzią.

Zachowanie pamięci podręcznej (Cache)

API nie ustawia Cache-Control ani ETag w odpowiedziach. Każde wywołanie trafia do backendu. Jeśli potrzebujesz cache'owania, dodaj je po swojej stronie.

Nagłówki odpowiedzi celu

Nagłówki, które zwróciła docelowa strona, nie znajdują się w odpowiedzi z API FourA. Wracają one wewnątrz koperty JSON jako pole headers. Dla endpointów Single i Proxy jest to tablica obiektów nagłówków dla każdego skoku (jeden wpis na krok przekierowania). Dla endpointu Browser jest to płaski obiekt końcowych nagłówków 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 celu, odczytaj go z pola headers koperty, a nie z odpowiedzi HTTP samego wywołania API.

Powiązane

• API Endpoints: Kształty kopert żądań i odpowiedzi
• API Errors: Jak zbudowane są odpowiedzi o błędach
• Request Outcomes: Które wyniki podlegają opłacie
• Activity Log: Historia na żądanie z kluczem po ID żądania