Response-Header

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

Von FourA gesetzte Header

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 korrelieren 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 deinem Application-Log-Eintrag. Wenn sich ein Kunde beschwert, dass "die Daten um 14:32 Uhr falsch waren", kannst du den exakten Request erneut ausführen.
• Dashboard-Tracing: Dieselbe ID wird im Activity-Feed für von dir verwaltete Keys angezeigt, sodass du den passenden Eintrag öffnen und den erfassten Request sowie die Response analysieren kannst.

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 Aufrufs an, den du gerade getätigt hast. Es ist ein Zähler, keine Rechnung: Der Header zeigt an, was der Vorgang unabhängig vom Ergebnis verbraucht hat. Die Abrechnungsschicht des Dashboards rechnet nur abrechenbare Ergebnisse auf deinen Plan an (siehe Request Outcomes für Informationen dazu, welche Ergebnisse abrechenbar sind).

Kostenreferenz

/api/auto/ ist ein Request in deinem Dashboard, dessen Credit-Kosten der Summe der intern ausgeführten Unteraufrufe entsprechen (ein einzelnes Replay auf einem warmen Ziel kann bei 2 enden; ein Cold Solve auf einer schwierigen Seite kann deutlich mehr verbrauchen). Der X-FourA-Credits-Wert 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 lesen, neben deiner Request-Zeile protokollieren oder über viele Aufrufe hinweg ohne JSON-Parsing summieren. Das meta.credits-Feld des Bodys (Auto) oder die Metadaten pro Engine (Single-, Proxy-, Browser-Dashboards) enthalten dieselbe Zahl, jedoch lesbar innerhalb des Response-Envelopes.

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 zwischen "mein Plan hat dies gestoppt" und "FourA ist ausgelastet" zu unterscheiden.

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 exitCountries-Parameter 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 jeweils enthaltenen Body-Felder findest du unter Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class nennt die Exit-Klasse, die den Body ausgeliefert hat: premium, wenn es ein Premium-Exit war, standard beim Standard-Pool. Er erscheint in einer POST /api/proxy/-Response, die eine Seite ausgeliefert hat, wenn der Request einen exitClass angegeben hat (wobei der Body denselben Wert enthält), sowie in einer Single- oder Browser-Response, wenn der von dir gepinnte proxy ein Premium-Exit war (wobei der Body kein Feld dafür hat). Ein fehlgeschlagener Proxy-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 zu deinem Premium-Traffic als auch zu deiner gesamten Bandbreite. Er wird auf Netzwerkebene gemessen und umfasst auch Premium-Versuche, die deine Seite nicht zurückgegeben haben. Ein Request, der mit standard beantwortet wurde, kann also dennoch Premium-Traffic verbraucht haben, wenn ein Versuch fehlschlug, bevor der Standard-Pool geantwortet hat. Dieser Header nennt die ausliefernde Klasse, nicht ob Premium-Traffic verbraucht wurde: Die Kennzeichnung premium in einer Activity-Zeile und die Seite Usage & Limits zeigen an, was gezählt wurde. Was exitClass bewirkt und wann ein Premium-Exit genutzt wird: exitClass.

Cache-Verhalten

Die API setzt weder Cache-Control noch ETag in den Responses. Jeder Call erreicht das Backend. Wenn du Caching benötigst, implementiere es auf deiner Seite.

Response-Header des Ziels

Die vom Zielsystem zurückgegebenen Header befinden sich nicht im 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 mit den finalen Response-Headern.

{
  "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 headers-Feld des Envelopes aus, nicht aus der HTTP-Response des API-Aufrufs selbst.

Verwandte Themen

• API-Endpoints: Struktur von Request- und Response-Envelopes
• API-Fehler: Wie Fehler-Responses aufgebaut sind
• Request-Ergebnisse: Welche Ergebnisse abrechenbar sind
• Aktivitätsprotokoll: Historie pro Request, zugeordnet nach Request-ID
• Rate Limits: Bedeutung der einzelnen X-FourA-Limit-Werte