Response-Header

Jede Antwort der FourA-API enthält eine kleine Auswahl benutzerdefinierter Header. Sie sind nützlich für Tracing, Support, Abrechnungsabgleich und nachträgliche Analysen.

Header, die FourA setzt

Header Gesetzt bei Beschreibung
X-FourA-Request-Id Jeder /api/*-Antwort, einschließlich Fehlern und 401s, außer bei einem Body, den FourA überhaupt nicht lesen kann (400 Invalid JSON in request body, 413), der abgelehnt wird, bevor eine ID zugewiesen wird Eine UUID, die diesen Request identifiziert. Protokolliere sie auf deiner Seite.
X-FourA-Credits Jeder /api/*-Antwort, die das Backend erreicht hat Für diesen Aufruf verbrauchte Credits. Wird bei Erfolg und bei Fehlschlag zurückgegeben (die Arbeit wurde in beiden Fällen erledigt).
X-FourA-Limit Jedem 403 oder 429, der durch ein Limit deines Tarifs ausgelöst wurde Welches Limit den Aufruf abgelehnt hat: plan_limit_ gefolgt von feature, premium, concurrency, rate, browser_daily, credits oder bandwidth.
Retry-After Tariflimit-429s, die sich durch Warten auflösen (Parallelität, Rate, Credits, Bandbreite) und dem 503 API key check temporarily unavailable Wartezeit in Sekunden als Ganzzahl. Entspricht retry_after_seconds in einem Tariflimit-Body und retryAfter beim 503.
X-FourA-Exit-Class Jedem /api/proxy/- oder /api/auto/-Aufruf, der ein exitClass benannt und eine Seite ausgeliefert hat, sowie jedem Single- oder Browser-Aufruf, der über einen Premium-Exit bedient wurde premium oder standard: die Exit-Klasse, die den Body ausgeliefert hat. Ein fehlgeschlagener Proxy-Aufruf hat nichts ausgeliefert und enthält keinen Header.
X-FourA-Browser-Used-Today Jeder POST /api/browser/-Antwort, die nicht durch Limits deines Tarifs abgelehnt wurde, und jeder POST /api/auto/-Antwort, deren Ladder einen Request gesendet hat, der nicht abgelehnt wurde Heute für dein Konto gezählte Browser-Requests: siehe unten.
X-FourA-Browser-Limit-Per-Day Denselben Antworten, wenn dein Tarif ein tägliches Kontingent festlegt Browser-Requests, die dein Tarif pro Tag erlaubt.
X-FourA-Check-Page Single-, Proxy-Finder- und Browser-Antworten, deren HTTP-200-Body eine von FourA erkannte Bot-Prüfung oder Ablehnungsseite ist Der Name der Seite, zum Beispiel amazon-captcha. Ein solcher Request wird nicht abgerechnet: siehe Request Outcomes.
Content-Type Jeder Antwort Immer application/json für das Envelope. Der Content-Type des Ziels wird im Feld headers des Envelopes zurückgegeben.

X-FourA-Request-Id

Jeder Aufruf von POST /api/auto/, POST /api/single/, POST /api/proxy/ oder POST /api/browser/ ist mit einer UUID versehen. Der Header wird auch dann gesetzt, wenn die Authentifizierung fehlschlägt, sodass du auch falsch konfigurierte Aufrufe zuordnen kannst.

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

Wann du es verwenden solltest

  • Support-Tickets: Gib die Request-ID an, damit wir den genauen Aufruf in unseren Logs finden können.
  • Eigene Logs: Speichere sie zusammen mit deiner Anwendungs-Logzeile. Wenn eine Kundenbeschwerde meldet, dass die Daten um 14:32 Uhr falsch waren, kannst du den exakten Request wiederholen.
  • Tracing im Dashboard: Dieselbe ID erscheint im Activity-Feed für von dir verwaltete Keys. So kannst du den passenden Eintrag öffnen und den erfassten Request sowie die Response prüfen.

Beispiel: Logging auf deiner Seite

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 gibt die Credit-Kosten des soeben getätigten Aufrufs an. Es ist ein Zähler, keine Rechnung: Der Header spiegelt wider, was die Verarbeitung unabhängig vom Ergebnis verbraucht hat. Die Abrechnungsschicht des Dashboards rechnet nur abrechenbare Ergebnisse auf deinen Plan an (siehe Request Outcomes für abrechenbare Ergebnisse).

Kostenübersicht

Engine Base With unblocker
Single 1 2
Proxy 2 4
Browser 5 10 (when a defense was solved)

/api/auto/ ist ein einzelner Request in deinem Dashboard, dessen Credit-Kosten der Summe der intern ausgeführten Sub-Calls entsprechen (ein einzelnes Replay auf einem vorbereiteten Ziel kann bei 2 enden; ein Cold Solve auf einer schwierigen Seite kann deutlich mehr verbrauchen). Der Wert X-FourA-Credits in der Auto-Response entspricht meta.credits im Body und erfasst die gesamten Ladder-Kosten.

Warum sowohl ein Header als auch ein Body-Feld?

Der Header ist praktisch: Du kannst ihn vor dem Parsen des Bodys auslesen, neben deiner Request-Zeile protokollieren oder über viele Aufrufe hinweg ohne JSON-Parsing aufsummieren. Bei Auto enthält meta.credits im Body denselben Wert. Die Bodys von Single, Proxy und Browser enthalten ihn nicht, daher ist der Header bei diesen Responses die einzige Stelle, um ihn auszulesen. Die Zeile Activity jedes Aufrufs zeigt ihn ebenfalls an.

X-FourA-Limit

X-FourA-Limit erscheint nur, wenn ein Limit deines Plans den Aufruf abgelehnt hat. Die geteilten Rate Limits der Plattform setzen ihn nie. Der Header ist daher der schnellste Weg, um ohne Parsen des Bodys zu unterscheiden, ob dein Plan dies blockiert hat oder FourA ausgelastet ist.

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

Zwei der sieben Werte werden mit einem 403 statt einem 429 zurückgegeben: plan_limit_feature (der Endpoint oder der Parameter exitCountries ist nicht in deinem Plan enthalten) und plan_limit_premium (exitClass: premium ist nicht in deinem Plan enthalten). Keiner von beiden setzt Retry-After, da Warten das Ergebnis nicht ändert.

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

Die sieben Werte und die jeweiligen Body-Felder findest du unter Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class gibt die Exit-Klasse an, die den Body geliefert hat: premium bei einem Premium-Exit, standard beim Standard-Pool. Der Header erscheint in einer POST /api/proxy/- oder POST /api/auto/-Response mit Seiteninhalt, wenn der Request einen exitClass angegeben hat (der Body enthält denselben Wert: exitClass bei Proxy, meta.exitClass bei Auto). Er erscheint zudem in einer Single- oder Browser-Response, wenn der von dir festgelegte proxy ein Premium-Exit war (wo der Body kein Feld dafür enthält). Ein fehlgeschlagener Proxy- oder Auto-Aufruf liefert nichts aus und enthält daher weder den Header noch das Feld.

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

Traffic über einen Premium-Exit zählt sowohl für deinen Premium-Traffic als auch für deine gesamte Bandbreite. Er wird auf Netzwerkebene gemessen und beinhaltet auch fehlgeschlagene Premium-Versuche. Ein Request, der mit standard beantwortet wurde, kann also dennoch Premium-Traffic verbraucht haben, wenn ein Versuch fehlschlug, bevor der Standard-Pool antwortete. Dieser Header benennt die Klasse, die geliefert hat, nicht, ob Premium-Traffic verbraucht wurde: Die premium-Markierung in einer Activity-Zeile und die Seite Nutzung & Limits zeigen an, was gezählt wurde. Was exitClass bewirkt und wann ein Premium-Exit verwendet wird: exitClass.

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

Diese beiden Header enthalten dein tägliches Browser-Kontingent direkt in der Response. Es sind dieselben Werte, die auch die Seite Nutzung & Limits anzeigt. Du kannst den Verbrauch so ohne Polling des Dashboards verfolgen.

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

Die Zählung beginnt um Mitternacht UTC erneut und umfasst jeden Key deines Plans, nicht nur den dieses Aufrufs. Ein Request, der durch Limits deines Plans abgelehnt wurde, enthält keinen der beiden Header: Sein Body enthält stattdessen used_today und limit_per_day, siehe Rate Limits.

Bei POST /api/browser/ enthält der Zähler den Request, den du gerade liest. Bei POST /api/auto/ ist es der höchste Zählerstand, den die Ladder während ihrer Ausführung erhalten hat; er kann also hinter dem Tageswert zurückbleiben, wenn andere Requests noch laufen. Eine Auto-Antwort, die keinen Request gesendet hat, wie die 120-Sekunden-Pause nach wiederholten Fehlern auf einer Site, enthält keinen der beiden Header. Wie viel ein Auto-Aufruf vom Kontingent verbraucht hat, steht in meta.browserRequests: siehe Smart Fetch.

Cache-Verhalten

Die API setzt kein Cache-Control. Eine Response kann ein schwaches ETag tragen, das aus ihrem Body berechnet wurde, aber nichts wird zwischengespeichert: Jeder Aufruf trifft das Backend. Wenn du Caching benötigst, implementiere es auf deiner Seite.

Target-Response-Header

Die von der Zielseite zurückgegebenen Header befinden sich nicht in der FourA-API-Response. Sie werden im JSON-Envelope im Feld headers zurückgegeben. Für die Single- und Proxy-Endpoints ist dies ein Array von Header-Objekten pro Hop (ein Eintrag pro Redirect-Schritt). Für den Browser-Endpoint ist es ein flaches Objekt der finalen Response-Header.

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

Wenn du einen bestimmten Ziel-Header benötigst, lies ihn aus dem Feld headers des Envelopes aus, nicht aus der HTTP-Response des eigentlichen API-Aufrufs.

Aktualisiert: 5. November 2026