Response-Header

Jede Response der FourA API enthält einige benutzerdefinierte Header. Sie sind nützlich für Tracing, Support, den Rechnungsabgleich und die nachträgliche Analyse.

Von FourA gesetzte Header

Header	Gesetzt bei	Beschreibung
`X-Foura-Request-Id`	Jeder `/api/*` Response, inklusive Fehlern und 401s	Eine UUID zur Identifikation dieses Requests. Logge sie auf deiner Seite.
`X-FourA-Credits`	Jeder `/api/*` Response, die das Backend erreicht hat	Verbrauchte Credits für diesen Aufruf. Wird bei Erfolg und bei Fehler zurückgegeben (die Arbeit wurde in jedem Fall erledigt).
`Content-Type`	Jeder Response	Immer `application/json` für den Envelope. Der Content-Type des Ziels wird innerhalb des Feldes `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 bei fehlgeschlagener Authentifizierung gesetzt, sodass du auch fehlerhaft 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 ihn verwenden solltest

Support-Tickets: Füge die Request-ID hinzu, damit wir den genauen Aufruf in unseren Logs finden.
Deine eigenen Logs: Speichere sie neben deiner Anwendungs-Logzeile. Wenn eine Kundenbeschwerde besagt "die Daten waren um 14:32 falsch", kannst du den genauen Request nachstellen.
Dashboard-Tracing: Dieselbe ID erscheint im Aktivitäts-Feed für Schlüssel, die du verwaltest. So kannst du die passende Zeile öffnen und den erfassten Request und Response prüfen.

Beispiel: Loggen 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 meldet die Credit-Kosten des soeben getätigten Aufrufs. Es ist ein Zähler, keine Rechnung: Der Header spiegelt den Arbeitsaufwand wider, unabhängig vom Ergebnis. Die Abrechnungsschicht des Dashboards rechnet nur abrechenbare Ergebnisse auf deinen Plan an (siehe Request-Ergebnisse dafür, welche Ergebnisse abrechenbar sind).

Kostenübersicht

Engine	Basis	Mit `unblocker`
Single	1	2
Proxy	5	10
Browser	15	30 (wenn eine Abwehr gelöst wurde)

/api/auto/ fügt keine separate abrechenbare Zeile hinzu. Seine Credit-Kosten sind die Summe der intern durchgeführten Sub-Aufrufe (ein einzelnes Replay auf einem warmen Ziel kann bei 2 enden; ein kaltes Solve auf einer harten Seite kann viel mehr verbrauchen). Der Wert X-FourA-Credits auf dem Auto-Response entspricht meta.credits im Body und trackt die gesamten Leiterkosten.

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 ihn über viele Aufrufe hinweg ohne JSON-Parsing summieren. Das Feld meta.credits des Bodys (Auto) oder die Metadaten pro Engine (Single, Proxy, Browser Dashboards) enthalten dieselbe Zahl, sind aber innerhalb des Response-Envelopes lesbar.

Cache-Verhalten

Die API setzt keine Cache-Control oder ETag bei Responses. Jeder Aufruf erreicht das Backend. Wenn du Caching benötigst, füge es auf deiner Seite hinzu.

Ziel-Response-Header

Die von der Zielseite zurückgegebenen Header befinden sich nicht im Response der FourA API. Sie kommen innerhalb des JSON-Envelopes als headers-Feld zurück. Für die Endpoints Single und Proxy 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 headers-Feld des Envelopes, nicht aus dem HTTP-Response des API-Aufrufs selbst.