Site-Checks

Wenn ein Ziel auf dem Weg zu der von dir angeforderten Seite einen Bot-Check durchführt, teilt FourA dir das mit. Jeder Request, der auf einen solchen Check trifft, enthält ein Feld mit dem Namen des Systems, der Information, ob der Check bestanden wurde, und (bei Erfolg) den Clearance-Daten zum Wiederverwenden, damit der nächste Aufruf ihn überspringt.

Diese Seite ist die Referenz für diese Felder. Informationen zur Strategie findest du unter Geschützte Websites.

Wo sich das Feld befindet

Endpoint	Feld	Vorhanden wenn
`POST /api/single/`	`defense` (object)	Ein Bot-Check in der Response erkannt wurde
`POST /api/proxy/`	`defense` (object)	Ebenso, gemeldet von dem Versuch, der geantwortet hat
`POST /api/browser/`	`defenseSolved` (boolean) und `defenses` (object)	Immer, bei einer geladenen Seite. `defenseSolved` ist `false` und `defenses` ist leer, wenn nichts erkannt wurde.
`POST /api/auto/`	`meta.solved` (boolean)	Bei jeder Antwort, sobald die Ladder gestartet ist. `true`, wenn ein Check irgendwo auf der Ladder gelöst wurde. Ein Body, der die Validierung nicht besteht, oder ein Host, der nicht auflöst, wird vor der Ladder beantwortet, ohne `meta`.

Fehlt das Feld, wurde nichts erkannt. Interpretiere ein fehlendes defense nicht als Fehler.

Bei Single und Proxy erfordert das Reporting unblocker, was standardmäßig aktiviert ist. Mit unblocker: false forderst du die Seite exakt so an, wie sie geliefert wurde; Single gibt die Challenge somit unverändert zurück und Browser rendert sie, ohne sie zu lösen.

`defense` auf Single und Proxy

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "hashes": 1048576,
    "complexity": 20,
    "cookie": "_I_=<clearance>"
  }
}

Feld	Typ	Beschreibung
`vendor`	string	Das System, um das es in diesem Datensatz geht: dasjenige, das gelöst wurde, oder das primär angetroffene. Siehe Vendor-Liste unten.
`solved`	boolean	`true` bedeutet, dass die Prüfung gelöst wurde und `data` die echte Seite ist. `false` bedeutet, dass `data` die Challenge-Seite sein kann.
`present`	string[]	Jedes in dieser Response erkannte System. Kann mehr Namen enthalten als `vendor` und auch Namen umfassen, die bisher niemand löst.
`ms`	number	Millisekunden, die für das Lösen der Prüfung aufgewendet wurden. Nur bei gelöster Prüfung.
`hashes`	number	Wie viel Rechenaufwand die Challenge verlangt hat. Nur bei gelöster Prüfung.
`complexity`	number	Die von der Challenge gemeldete Schwierigkeit. Nur bei gelöster Prüfung und nur, wenn die Challenge einen Wert meldet.
`answers`	number	Wie viele akzeptierte Antworten geliefert wurden, bei Challenges, die mehrere statt nur einer verlangen. Nur bei gelöster Prüfung.
`retry`	string	Vorhanden, wenn der Body aus einem Retry statt aus einer gelösten Prüfung stammt. Aktuell ist der einzige Wert `refusal-cookies`. Siehe unten.
`cookie`	string	Das Cookie-Jar für das Replay: das Clearance-Cookie einer gelösten Prüfung oder die Session, die bei einer Verweigerung ausgegeben wurde.

solved: false ist der Fall, auf den du verzweigen solltest. FourA liefert niemals eine Challenge-Seite als Inhalt aus. Das Flag ist daher dein Signal, dass der Body eskaliert statt geparst werden muss.

`retry: "refusal-cookies"`

Manche Websites nutzen kein Puzzle. Sie verweigern den ersten Request, setzen Cookies bei der Verweigerung und liefern die echte Seite an jeden aus, der diese Cookies zurücksendet. Artikelseiten von eBay sind der Referenzfall.

In diesem Fall sendet FourA diese Cookies für dich zurück und liefert dir die Seite. Die Response enthält dann retry: "refusal-cookies":

{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai"],
    "retry": "refusal-cookies",
    "cookie": "bm_sv=...; dp1=..."
  }
}

Lies es so:

solved bleibt false. Das Beantworten eines Handshakes ist kein Lösen einer Challenge und ändert nie die Kosten des Calls. Dir wird der ausgeführte Request berechnet.
data ist echter Inhalt, keine Challenge-Seite. Dies ist der einzige Fall, in dem solved: false nicht bedeutet, dass der Body eine Eskalation erfordert. Deshalb existiert dieses Feld.
cookie ist die Session, die die Website vergeben hat. Spiele sie genauso wieder ein, wie du eine Clearance einspielen würdest, und nachfolgende Seiten überspringen die Verweigerung.
Ein Retry und ein Clear können beide bei einem einzigen Request auftreten. Wenn die Antwort des Retrys eine Challenge war, die FourA lösen kann, erhältst du solved: true mit den Feldern des Anbieters und retry: "refusal-cookies" daneben.

vendor lautet unknown, wenn ein Retry den Inhalt geliefert hat und dabei kein System erkannt wurde. present ist dann ein leeres Array.

`defenses` auf Browser

{
  "status": 200,
  "body": "<!doctype html>...",
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {
    "present": ["cloudflare"],
    "cleared": ["cloudflare"]
  }
}

Feld	Typ	Beschreibung
`defenseSolved`	boolean	`true`, wenn beim Laden ein System erkannt wurde und dessen Freigabe auf der finalen Seite erhalten bleibt. Dieses Flag entscheidet, ob der Aufruf 5 oder 10 Credits kostet.
`defenses.present`	string[]	Jedes System, das zu irgendeinem Zeitpunkt während des Seitenaufbaus erkannt wurde, nicht nur in der finalen Response. Eine Überprüfung hat stattgefunden, und sobald die eigentliche Seite eintrifft, ist die Challenge-Response längst vergangen.
`defenses.cleared`	string[]	Die Systeme, deren Freigabe auf der finalen Seite vorliegt.

Ein Name in present, der cleared nie erreicht, ist ein System, das FourA zwar erkennen, aber noch nicht abschließen kann. Diese erhöhen den Preis eines Aufrufs nie.

Anbieter

`vendor`-Wert	Das System
`cloudflare`	Cloudflare Challenges und Bot-Management
`sgcaptcha`	SiteGround Site-Check
`datadome`	DataDome
`perimeterx`	PerimeterX
`akamai`	Akamai Bot Manager
`incapsula`	Imperva Incapsula
`awswaf`	AWS WAF Challenge
`ebay-splashui`	Eigene Challenge von eBay
`reddit`	Eigene Überprüfungs- und Ablehnungsseiten von Reddit
`amazon`	Amazon Robot-Check
`google`	JavaScript-Check der Google-Suche
`hcaptcha`	hCaptcha
`recaptcha`	reCAPTCHA
`unknown`	Es wurde kein System erkannt. Erscheint nur zusammen mit `retry`, wo der Eintrag existiert, um den Retry statt eines Anbieters zu melden.

Was heute gelöst wird

Endpoint	Löst
Single, Proxy	`sgcaptcha`, `ebay-splashui`. Beide sind rechnerisch statt visuell, daher ist kein Browser beteiligt.
Browser	`cloudflare`, `sgcaptcha`

Alles andere auf der Liste wird lediglich erkannt und gemeldet. Diese Aufteilung ändert sich, sobald FourA lernt, mehr davon zu lösen. Lies daher solved aus, anstatt dich auf diese Tabelle zu verlassen.

Zwei Hinweise zu Randfällen:

hcaptcha und recaptcha sind auch gewöhnliche Formular-Widgets. Sie werden nur gemeldet, wenn die Response dich tatsächlich blockiert hat (403, 429 oder 503). Eine Checkout-Seite mit einem Verifizierungs-Widget in einem Formular meldet also keine Defense.
Hinter Cloudflare zu liegen ist keine Defense. cloudflare erscheint, wenn eine echte Challenge oder ein Bot-Management-Artefakt in der Response vorliegt, nicht bloß weil eine Website Cloudflare nutzt.

Eine Freigabe wiederverwenden

defense.cookie ist der eigentliche Zweck dieses Felds. Eine Freigabe ist an die Exit-IP und den User-Agent gebunden, die sie erlangt haben. Sende sie über dasselbe Paar erneut, und die Überprüfung wird nicht noch einmal ausgeführt.

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
    "maxTries": 5,
    "request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()

defense = first.get("defense", {})
if defense.get("solved"):
    clearance = defense["cookie"]
    exit_id = first["proxy"]

    # 2) Follow-up pages skip the check: same exit, same clearance.
    for page in range(2, 6):
        r = requests.post(f"{API}/api/single/", headers=H, json={
            "method": "GET",
            "url": f"https://example.com/catalog?page={page}",
            "proxy": exit_id,
            "headers": [["Cookie", clearance]],
        }).json()
        print(page, r["status"])

Der erste Aufruf trägt die Kosten des Clearings. Jeder Replay ist ein gewöhnlicher Request zum regulären Preis.

Drei Dinge machen einen Replay ungültig:

Ein anderer Exit. Pinne die Proxy-ID, die die Clearing-Response zurückgegeben hat. Siehe Reuse a Proxy Across Requests.
Ein anderer User-Agent. Browser-Responses geben den verwendeten userAgent zurück. Sende ihn zusammen mit dem Cookie zurück.
Ablauf. Clearances haben eigene, vom Ziel gesetzte Gültigkeitsdauern. Bei SiteGround sind es etwa 30 Tage für die gesamte Website; ein Cloudflare-Clearance ist meist deutlich kürzer. Behandle ein Clearance wie einen Cache: Wenn Replays wieder Challenges zurückgeben, führe einen neuen Aufruf aus und übernimm das neue Clearance.

Was es kostet

Ein gelöster Check ändert den Preis nur bei Browser:

Engine	Base	Cleared defense
Single	1 (2 mit `unblocker`)	Keine Änderung
Proxy	2 (4 mit `unblocker`)	Keine Änderung
Browser	5	10

Browser berechnet 10 nur dann, wenn der Solver aktiv war und ein System tatsächlich gelöst wurde. Ein erkanntes, aber nicht gelöstes System kostet 5, genau wie eine Seite ganz ohne Check.

Eine von FourA erkannte Check-Seite, die mit HTTP 200 ausgeliefert wird (zum Beispiel der Robot-Check von Amazon, die Verifizierungsseite von Reddit oder der JavaScript-Check der Google-Suche), wird auf keinem Endpoint abgerechnet; die Response benennt sie in X-FourA-Check-Page.

Kombiniere es mit `validate`

defense teilt dir mit, dass ein Check aufgetreten ist. validate teilt FourA mit, wie die echte Seite aussieht. Dadurch schlägt ein Request fehl, anstatt dir ein Interstitial zu liefern, das zufällig HTTP 200 hat.

{
  "method": "GET",
  "url": "https://example.com/product/42",
  "validate": {
    "data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
  }
}

Auf POST /api/auto/ verhindert validate, dass die Ladder eine Challenge-Seite fälschlicherweise als erfolgreich wertet.

Site-Checks

Wo sich das Feld befindet

defense auf Single und Proxy

retry: "refusal-cookies"

defenses auf Browser