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 Angabe, ob die Überprüfung bestanden wurde, und (bei Erfolg) dem Clearance-Token, das du wiederverwenden kannst, damit der nächste Aufruf ihn überspringt.
Diese Seite ist die Referenz für diese Felder. Strategien dazu findest du unter Geschützte Websites.
Wo sich das Feld befindet
| Endpoint | Feld | Vorhanden wenn |
|---|---|---|
POST /api/single/ |
defense (Objekt) |
In der Response wurde ein Bot-Check erkannt |
POST /api/proxy/ |
defense (Objekt) |
Ebenso, gemeldet vom antwortenden Versuch |
POST /api/browser/ |
defenseSolved (Boolean) und defenses (Objekt) |
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 wurde. true, wenn irgendwo in der Ladder ein Check bestanden wurde. Ein Body, der die Validierung nicht besteht, oder ein Host, der nicht aufgelöst werden kann, wird vor der Ladder beantwortet, ohne meta. |
Fehlen bedeutet, dass nichts erkannt wurde. 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 ankam; Single gibt die Challenge daher unverändert zurück und Browser rendert sie, ohne sie zu lösen.
defense bei 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, auf das sich dieser Datensatz bezieht: dasjenige, das gelöst wurde, oder das wichtigste erkannte System. Siehe die Anbieterliste unten. |
solved |
boolean | true bedeutet, dass die Prüfung bestanden wurde und data die eigentliche 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, auch Namen, die bisher niemand auflöst. |
ms |
number | Für das Bestehen der Prüfung aufgewendete Millisekunden. Nur bei erfolgreichem Clear. |
hashes |
number | Wie viel Rechenaufwand die Challenge verlangt hat. Nur bei erfolgreichem Clear. |
complexity |
number | Der von der Challenge gemeldete Schwierigkeitsgrad. Nur bei erfolgreichem Clear und nur, wenn die Challenge einen angibt. |
answers |
number | Wie viele akzeptierte Antworten geliefert wurden, falls die Challenge mehrere statt nur einer verlangt. Nur bei erfolgreichem Clear. |
retry |
string | Vorhanden, wenn der Body aus einem Retry statt aus einem Clear stammt: refusal-cookies, amazon-continue, reddit-js-check oder verify-challenge. Siehe unten. |
cookie |
string | Das Jar zum erneuten Senden: die durch das Lösen erhaltene Freigabe oder die bei einer Ablehnung vergebene Session. |
solved: false ist der Fall, nach dem du verzweigen solltest. FourA liefert eine Challenge-Seite niemals als Inhalt aus, daher signalisiert dir das Flag, dass der Body eskaliert und nicht geparst werden muss.
retry: "refusal-cookies"
Manche Websites verwenden kein Puzzle. Sie lehnen den ersten Request ab, setzen Cookies bei der Ablehnung und liefern die eigentliche Seite an jeden aus, der diese Cookies zurücksendet. Die Artikelseiten von eBay sind der Referenzfall.
In diesem Fall sendet FourA sie für dich zurück und übergibt 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:
solvedbleibtfalse. Das Beantworten eines Handshakes ist kein Lösen einer Challenge und ändert nie die Kosten des Calls. Dir wird der Request berechnet, den du gestellt hast.dataist echter Inhalt, keine Challenge-Seite. Dies ist der einzige Fall, in demsolved: falsenicht bedeutet, dass der Body eine Eskalation benötigt. Genau deshalb existiert dieses Feld.cookieist die Session, die die Seite ausgegeben hat. Spiele sie genauso wieder ab, wie du ein Clearance wiederholen würdest, und nachfolgende Seiten überspringen die Ablehnung.- 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: truemit den Feldern des Anbieters undretry: "refusal-cookies"daneben.
vendor liefert unknown, wenn ein Retry den Inhalt geliefert hat und unterwegs kein System erkannt wurde. present ist dann ein leeres Array.
retry: "amazon-continue"
Amazon antwortet manchmal mit einem Ein-Klick-Robot-Check: eine kleine Seite, die dich auffordert zu klicken, um weiter einzukaufen, wobei die Antwort bereits ausgefüllt ist. Wenn unblocker aktiv ist (Standard), klicken Single und Proxy auf diesen Button über denselben Exit innerhalb deines timeout_ms und fordern deine Seite mit den gesetzten Cookies erneut an. Wenn das die Seite öffnet, enthält die Response retry: "amazon-continue":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "akamai",
"solved": false,
"present": ["akamai", "amazon"],
"retry": "amazon-continue",
"cookie": "ak_bmsc=...; ..."
}
}
Lies es wie einen Retry bei abgelehnten Cookies. solved bleibt false, data ist die eigentliche Seite, dir wird der von dir gesendete Request berechnet und cookie ist das Jar, das du bei Folgeaufrufen wiederverwenden kannst. Suche nach amazon in present statt in vendor: Die Prüfseite setzt oft ein Cookie, das FourA ebenfalls erkennt, und vendor nennt das erste System in der Liste.
Die Bildvariante derselben Prüfung, bei der ein Mensch die Antwort ablesen muss, wird gemeldet und unverändert weitergegeben. Ebenso ein Klick, der nur die Prüfung erneut lädt. In beiden Fällen wird diese Seite nicht berechnet (siehe Was es kostet).
retry: "reddit-js-check"
Reddit antwortet manchmal mit einem einfachen Seitencheck: eine kleine Seite mit einem versteckten Formular und einem Skript, das dieses Formular ausfüllt. Wenn unblocker aktiviert ist (Standardeinstellung), übermitteln Single und Proxy dieses Formular über denselben Exit innerhalb deines timeout_ms und rufen deine Seite mit den gesetzten Cookies erneut ab. Wenn sich die Seite dadurch öffnet, enthält die Response retry: "reddit-js-check":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "reddit",
"solved": false,
"present": ["reddit"],
"retry": "reddit-js-check",
"cookie": "edgebucket=...; ..."
}
}
Lies es wie einen amazon-continue Retry. solved bleibt false, data ist die echte Seite, dir wird der ausgeführte Request berechnet und cookie ist das Jar für Folgeseiten. Wenn der Check wiederholt erscheint, belässt FourA die Seite im Originalzustand und diese Seite wird nicht berechnet.
retry: "verify-challenge"
Manche Websites öffnen zunächst eine kurze eigene Prüfseite: ein Spinner und ein Skript, das dich nach Abschluss des Checks zur Seite weiterleitet. Wenn unblocker aktiviert ist (Standard), schließen Single und Proxy diesen Check auf demselben Exit innerhalb deines timeout_ms ab und fordern deine Seite mit dem gesetzten Cookie erneut an. Wenn dies die Seite öffnet, enthält die Response retry: "verify-challenge":
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "verify-challenge",
"solved": false,
"present": ["verify-challenge"],
"retry": "verify-challenge",
"cookie": "token=..."
}
}
Lies es wie einen reddit-js-check Retry. solved bleibt false, data ist die eigentliche Seite, dir wird der gesendete Request berechnet und cookie ist das Jar zum Wiederholen auf Folgeseiten. Wenn die Prüfseite unbeantwortet bleibt, wird sie nicht berechnet.
defenses im Browser
{
"status": 200,
"body": "<!doctype html>...",
"userAgent": "Mozilla/5.0...",
"defenseSolved": true,
"defenses": {
"present": ["cloudflare"],
"cleared": ["cloudflare"]
}
}
| Feld | Typ | Beschreibung |
|---|---|---|
defenseSolved |
boolean | true, wenn während des Ladens ein System erkannt wurde und dessen Clearance auf der finalen Seite vorliegt. Dieses Flag entscheidet, ob der Aufruf 5 oder 10 Credits kostet. |
defenses.present |
string[] | Jedes System, das zu irgendeinem Zeitpunkt während des Seitenladens erkannt wurde, nicht nur in der finalen Response. Eine Überprüfung ist ein reales Ereignis, und bis die eigentliche Seite eintrifft, ist die Challenge-Response längst vergangen. |
defenses.cleared |
string[] | Die Systeme, deren Clearance die finale Seite besitzt. |
Ein Name in present, der cleared nie erreicht, ist ein System, das FourA erkannt hat, ohne dafür eine Clearance zu erhalten: eines, das es noch nicht abschließen kann, oder eines der wenigen, die Browser anders verarbeitet (siehe Was heute gecleart wird). Diese erhöhen den Preis eines Aufrufs nie.
Anbieter
vendor-Wert |
Das System |
|---|---|
cloudflare |
Cloudflare-Challenges und Bot-Management |
sgcaptcha |
SiteGround-Website-Prüfung |
datadome |
DataDome |
perimeterx |
PerimeterX |
akamai |
Akamai Bot Manager |
incapsula |
Imperva Incapsula |
awswaf |
AWS WAF-Challenge |
ebay-splashui |
eBays eigene Challenge |
reddit |
Reddits eigene Prüf- und Ablehnungsseiten |
verify-challenge |
Eine seigene Prüfseite, die dich weiterleitet, sobald ihre Prüfung abgeschlossen ist |
amazon |
Amazons Robot-Prüfung |
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 gecleart wird
| Endpoint | Cleart |
|---|---|
| Single, Proxy | sgcaptcha, ebay-splashui. Beide sind rechnerisch statt visuell, daher wird kein Browser benötigt. |
| Browser | cloudflare, sgcaptcha |
Einige weitere werden ohne Clear verarbeitet. Single und Proxy betätigen Amazons Ein-Klick-Robot-Prüfung und melden sie als retry: "amazon-continue", übermitteln Reddits schlanke Seitenprüfung und melden sie als retry: "reddit-js-check" und schließen die seigene Prüfseite einer Website ab und melden sie als retry: "verify-challenge". Browser wartet bis zu 10 Sekunden darauf, dass dieselbe Prüfseite ihn weiterleitet. Browser klickt auf Amazons Button und wartet, während Akamais Sensorseite, AWS WAFs Challenge-Seite, DataDomes Geräteprüfung oder eBays eigene Challenge-Seite die nächste Seite selbstständig lädt, und liefert diese Seite dann zurück. Falls diese Seite nie eintrifft, liefert Browser die gehaltene Seite innerhalb deines timeout_ms zurück. Bei Browser erscheinen diese Namen in defenses.present, nie in cleared, und der Aufruf kostet 5.
Alles andere auf der Liste wird erkannt und gemeldet, mehr nicht. Diese Aufteilung verschiebt sich, sobald FourA weitere Systeme verarbeiten lernt; lies daher solved, anstatt dich auf diese Tabelle zu verlassen.
Zwei Randnotizen:
hcaptchaundrecaptchasind ebenfalls 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.
cloudflareerscheint, wenn eine echte Challenge oder ein Bot-Management-Artefakt in der Response vorliegt, nicht bloß weil eine Seite Cloudflare nutzt.
Clearance erneut abspielen
defense.cookie ist der eigentliche Zweck des Feldes. Eine Clearance ist an den Exit-Knoten und den User-Agent gebunden, über die sie erlangt wurde. Sende sie über dasselbe Paar erneut, und die Prü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 Clears. Jeder Replay ist ein normaler Request zum regulären Preis.
Drei Dinge bringen einen Replay zum Scheitern:
- Ein anderer Exit. Pinne die Proxy-ID, die die Response des Clears zurückgegeben hat. Siehe Reuse a Proxy Across Requests.
- Ein anderer User-Agent. Browser-Responses geben den genutzten
userAgentzurück. Sende ihn zusammen mit dem Cookie zurück. - Ablauf. Clearances haben eigene, vom Ziel gesetzte Gültigkeitsdauern. Die von SiteGround gilt etwa 30 Tage für die gesamte Website; eine Cloudflare-Clearance ist meist deutlich kürzer. Behandle eine Clearance wie einen Cache: Wenn Replays wieder Challenges zurückgeben, führe einen neuen Aufruf aus und übernimm die neue Clearance.
Kosten
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 ohne jeglichen Check.
Eine von FourA erkannte Check- oder Sperrseite mit HTTP 200 (beispielsweise der Robot-Check von Amazon, die Verifizierungsseite von Reddit oder die Challenge-Seite von eBay) wird an keinem Endpoint abgerechnet. Responses von Single, Proxy und Browser benennen sie in X-FourA-Check-Page.
Mit validate kombinieren
defense zeigt dir an, dass ein Check aufgetreten ist. validate teilt FourA mit, wie die echte Seite aussieht. Dadurch schlägt ein Request fehl, statt dir eine Zwischenseite mit zufälligem HTTP 200 zu liefern.
{
"method": "GET",
"url": "https://example.com/product/42",
"validate": {
"data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
}
}
Bei POST /api/auto/ verhindert validate, dass die Eskalationskette eine Challenge-Seite fälschlicherweise als erfolgreich akzeptiert.
Verwandte Themen
- Geschützte Websites: Welche Engine für welche Schutzstufe geeignet ist
- API-Endpunkte: Request- und Response-Referenz für alle vier Endpunkte
- Proxy über Requests hinweg wiederverwenden: Den Exit festlegen, an den eine Freigabe gebunden ist
- Smart Fetch (Auto): Wie sich
meta.solvedin die Kette einfügt - Response-Header: Wo die Credit-Kosten eines Aufrufs aufgeführt werden