Häufige Probleme

Lösungen für die häufigsten Probleme bei der Nutzung der FourA-API.

Leerer oder unvollständiger Inhalt

Symptom: Die API gibt den Status 200 zurück, aber das Feld data ist leer oder enthält nicht den erwarteten Inhalt.

Ursache: Die Zielseite nutzt JavaScript, um Inhalte nach dem initialen Laden der Seite zu rendern.

Lösung: Wechsle vom Single-Endpoint zum Browser-Endpoint. Nutze checkText, um zu prüfen, ob der Inhalt geladen wurde:

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Hinweis: Der Browser-Endpoint gibt Inhalte im Feld body zurück (nicht data).

403 Forbidden oder Verifizierungsseiten

Symptom: Die API gibt HTML zurück, das eine Verifizierungsseite oder eine Seite mit Zugriffsverweigerung enthält.

Ursache: Die Zielseite hat die Request als automatisiert erkannt und blockiert.

Lösung: Verwende den Proxy-Endpoint für automatische IP-Rotation:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

Besteht das Problem weiterhin, erhöhe maxTries, um der Proxy-Rotation mehr Versuche zu geben.

Ein vom Ziel zurückgegebener 403-Fehler kommt als HTTP 200 mit status: 403 im Body an. Ein 403-Fehler beim Aufruf selbst, mit einem X-FourA-Limit-Header, ist etwas anderes: Siehe 403 Not in Your Plan.

Timeout-Fehler

Symptom: Requests schlagen mit einem Timeout-Fehler fehl.

Ursache: Die Zielseite braucht länger zum Laden als der konfigurierte Timeout.

Lösung: Erhöhe timeout_ms (Standard ist 15s für Single, 30s für Browser, 45s für Proxy):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

Prüfe bei Browser-Requests auch, ob dein checkText-Wert tatsächlich auf der Seite vorkommt. Ein Tippfehler lässt den Call mit checkText:<your text> not found fehlschlagen.

403 Nicht in deinem Plan

Symptom: Die API gibt 403 mit einem X-FourA-Limit-Header und einem reason von plan_limit_feature oder plan_limit_premium zurück.

{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

Ursache: Dein Plan enthält den aufgerufenen Endpoint oder den übergebenen Parameter nicht. plan_limit_feature deckt einen ausgeschlossenen Endpoint ab und exitCountries, exitState, exitCity, exitAsn oder exitOs ohne Geo-Targeting. plan_limit_premium deckt exitClass: premium ohne Premium-Exits ab sowie einen Proxy-Request, der einen Exit-Standort angibt, sobald dein Premium-Traffic aufgebraucht ist. Das Ziel wurde nie kontaktiert und es wurde nichts verbraucht.

Lösung: Entferne den Parameter, rufe einen Endpoint auf, den dein Plan enthält, oder führe ein Upgrade durch. Der Tab Limits & Features unter Nutzung & Limits listet auf, was dein Plan enthält. Wiederhole den Request nicht unverändert: Es ist kein Retry-After gesetzt, da Warten das Ergebnis nicht ändert.

429 Zu viele Anfragen

Symptom: Die API gibt 429 zurück.

Ursache: Eine von zwei Prüfungen hat den Aufruf abgelehnt, und die Response gibt Aufschluss darüber, welche es war. Enthält sie einen X-FourA-Limit-Header, wurde ein Limit deines Plans erreicht: gleichzeitige Requests oder Requests pro Minute auf diesem Endpoint, Browser-Requests für den Tag oder die Credits bzw. Bandbreite für den Abrechnungszeitraum. Gibt es keinen solchen Header, war das geteilte Minutenkontingent der Plattform für diesen Dienst ausgelastet, was am Traffic von FourA liegt und nicht an deinem.

Lösung: Lies zuerst X-FourA-Limit. Warte, wenn das Limit nur Sekunden entfernt ist, und stoppe, wenn dies nicht der Fall ist. Bei Plan-Limits, die sich durch Warten zurücksetzen, stehen die Sekunden im Header Retry-After und in retry_after_seconds; das geteilte Limit gibt sie in retryAfter an:

import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

Wenn der Header plan_limit_concurrency oder plan_limit_rate enthielt, besteht die Lösung darin, die Anzahl offener Aufrufe und neuer Aufrufe pro Minute zu begrenzen, anstatt aggressiver zu wiederholen. Das sofortige erneute Senden eines abgelehnten Batches führt dazu, dass der gesamte Batch erneut abgelehnt wird. Abgelehnte Aufrufe zählen nicht zu deinem Limit pro Minute. Wenn sie jedoch weiterhin mit mehr als dem Doppelten dieses Limits eingehen, führen die Ablehnungen zu einer Abkühlphase: Der 429-Body enthält cooldown: true und fordert dich auf, für 30 Sekunden zu pausieren (retry_after_seconds: 30). Requests parallel ausführen beschreibt das Muster, und Nutzung & Limits im Dashboard zeigt deine Live-Zähler neben deinen Obergrenzen an.

503 Dienst nicht verfügbar

Symptom: Die API gibt den Status 503 zurück.

Ursache: Dies tritt in drei Fällen auf:

  1. Der Dienst ist ausgelastet. FourA führt auf dieser Engine bereits so viele Requests gleichzeitig aus, wie maximal zulässig sind, gemessen am gesamten Traffic und nicht nur an deinem. Service at capacity im Feld error. Dies behebt sich meist innerhalb von Sekunden.
  2. Dienst vorübergehend deaktiviert. Ein Wartungsfenster ist aktiv. Service disabled im Feld error.
  3. FourA kann deinen Key vorübergehend nicht prüfen. API key check temporarily unavailable im Feld error mit Retry-After: 5. Dein Key ist gültig.

Alle drei Fälle enthalten ein Feld retryAfter in der Response. Keiner davon ist ein Plan-Limit: Die Limits deines eigenen Plans antworten immer mit einem Header X-FourA-Limit bei einem 403 oder einem 429, niemals mit 503.

Lösung: Warte retryAfter Sekunden und wiederhole den Aufruf dann:

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Ein 503 bei Kapazitätsgrenzen bedeutet, dass FourA ausgelastet ist. Warten und ein erneuter Versuch lösen das Problem bereits. Wenn du stattdessen mit 429 und X-FourA-Limit abgewiesen wirst, liegt es an dir: Reduziere die Anzahl paralleler Requests in deiner Pipeline.

504 Upstream-Timeout

Symptom: Die API gibt 504 mit {"error": "Upstream timeout"} zurück.

Ursache: Die Verarbeitung wurde nicht innerhalb des Zeitlimits abgeschlossen, das du für den Request festgelegt hast. Ein langsames Ziel, das Lösen einer Challenge ohne Cache oder eine sehr große Seite können dazu führen. Es liegt nicht an deinem Key, deinen Parametern oder deinem Proxy.

Lösung: Gib dem Aufruf mehr Zeit oder versuche es erneut. FourA wartet für deine timeout_ms plus einer kleinen Spanne, eine Erhöhung verlängert die Wartezeit also tatsächlich:

{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}

Für /api/auto/ auf einem geschützten Ziel kann ein erster Cold Call mehrere Dutzend Sekunden dauern. Sein timeout_ms deckt die gesamte Kette ab und akzeptiert bis zu 180000.

Wenn /api/auto/ dieses Budget selbst ausgeht, antwortet der Aufruf trotzdem mit HTTP 200. Der Body enthält ein error, das mit time budget exhausted beginnt, und status ist gewöhnlich 504 (ein früherer fehlgeschlagener Versuch kann stattdessen seinen eigenen Status dort hinterlassen). Erhöhe timeout_ms oder versuche es erneut.

502 Upstream nicht verfügbar

Symptom: Die API gibt 502 mit {"error": "Upstream unavailable"} oder 503 mit {"error": "Backend service unavailable"} zurück.

Ursache: FourA konnte seine eigene Engine nicht erreichen (Upstream unavailable), oder die Engine lieferte keine brauchbare Antwort (Backend service unavailable), meist weil eine Instanz neu startete. Auf /api/browser/ wartet eine Seite bis zu 10 Sekunden auf einen freien Browser, wenn alle belegt sind; wartet sie danach immer noch, wird dieser 503 zurückgegeben.

Lösung: Wiederhole den Aufruf mit einem kurzen Backoff. Beide gelten als service_error, und nur success wird abgerechnet. Ein Retry kostet dich also nichts extra. Wenn es länger als ein oder zwei Minuten dauert, prüfe die Statusseite.

401 Authentifizierungsfehler

Symptom: Jede Anfrage gibt 401 Unauthorized zurück.

Checkliste:

  1. Prüfe, ob der Header X-API-Key: YOUR_API_KEY lautet (nicht Authorization: Bearer oder Api-Key)
  2. Prüfe deinen API-Key auf zusätzliche Leerzeichen oder Zeilenumbrüche
  3. Erstelle einen neuen Key im Dashboard, falls der aktuelle kompromittiert sein könnte

400 Ungültige Anfrage

Symptom: Ein Aufruf von POST /api/single/, /api/proxy/ oder /api/browser/ gibt 400 mit {"error": "Invalid request: <field>: <reason>; ..."} zurück.

Ursache: Ein Feld in deinem Request-Body fehlt, hat den falschen Typ oder liegt außerhalb des gültigen Bereichs. Die Nachricht nennt bis zu fünf Felder, die nicht akzeptiert werden konnten, inklusive Begründung, gefolgt von and N more, falls es weitere gibt. Es wurde nichts abgerufen, das Ergebnis ist client_error und es werden keine Credits verbraucht.

Lösung: Korrigiere die genannten Felder und sende die Anfrage erneut. Derselbe Body erzeugt denselben 400-Fehler, wiederhole ihn daher nicht unverändert. Die Endpoint-Referenz listet jedes Feld mit Typ und Limits auf. Auf /api/auto/ wird derselbe Fehler als HTTP 200 mit status: 400 und dem Grund in error zurückgegeben.

400 Ziel verweist auf eine private oder reservierte IP-Adresse

Symptom: Die API gibt 400 mit Refusing to fetch <target>: target resolves to a private or reserved IP range zurück, bevor die Anfrage FourA verlässt.

Ursache: Deine url verweist auf einen privaten, Loopback- oder reservierten IP-Bereich (RFC 5735, RFC 6598 oder reservierte IPv6-Blöcke). FourA lehnt diese Ziele ab, damit das eigene Netzwerk nicht zum Erreichen interner Hosts genutzt werden kann.

Lösung: Rufe eine öffentliche URL ab. Verwende zum Testen ein öffentliches Ziel wie https://example.com oder https://httpbin.org/get. Falls dein Ziel ein selbst betriebener Dienst ist, stelle ihn zuerst unter einem öffentlichen Hostnamen bereit.

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

Ein Hostname, der nicht aufgelöst werden kann, wird nicht abgelehnt. Der Aufruf wird wie jedes Ziel, das FourA nicht erreichen kann, als HTTP 200 mit status: 0 und dem Grund (could not resolve <host>: <reason>) zurückgegeben, und er wird nicht abgerechnet.

400 Leerzeichen in der URL

Symptom: Single, Proxy oder Auto gibt 400 mit invalid URL: it contains a space; encode it as %20 (the URL as sent: "...") zurück, bevor der Request FourA verlässt.

Ursache: Die URL enthält ein Leerzeichen oder ein Steuerzeichen, meist ein Link, der wie geschrieben von einer Seite übernommen wurde (javascript: void(0), ein Teilen-Link mit enthaltenem Text). Es wird nichts abgerufen, das Ergebnis ist client_error und es werden keine Credits verbraucht.

Lösung: Kodiere die URL vor dem Senden (ein Leerzeichen ist %20) und überspringe Links, die keine Seiten sind, wie javascript:. Browser ruft eine solche URL so ab, wie Chrome es tut.

400 Ziel ist die FourA API selbst

Symptom: Die API gibt 400 mit Refusing to fetch <url>: that is the FourA API itself, not a page. zurück, bevor der Request FourA verlässt.

Ursache: Deine url verweist auf api.foura.ai oder eu.api.foura.ai. Ein Crawler tut dies meist, wenn er einen relativen Link einer Seite gegen die API-URL statt gegen die URL der Seite selbst auflöst, sodass /category/news/ zu https://eu.api.foura.ai/category/news/ wird. Es wird nichts abgerufen und es werden keine Credits verbraucht.

Lösung: Löse jeden Link vor dem Senden gegen die URL der Ursprungsseite auf, zum Beispiel mit urljoin(page_url, href) in Python. Der Inspect-Endpoint (/inspect) ist die einzige Adresse auf dem API-Host, die du über FourA abrufen kannst.

no_eligible_proxy bei Verwendung von exitCountries

Symptom: Ein /api/proxy/-Aufruf mit exitCountries gibt HTTP 200 mit einem JSON-Error-Envelope zurück:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

Ursache: Der aktuelle Proxy-Pool hat keinen funktionierenden Exit, dessen zielseitig sichtbares Land mit deiner Allowlist übereinstimmt. Der Standard-Pool weicht niemals auf ein nicht angefordertes Land aus, wenn du exitCountries setzt. Ohne exitCountries antwortet dieselbe Situation mit {"error": "Failed"}: FourA hatte keinen Exit zum Testen, wiederhole den Request also nach wenigen Sekunden.

Ein Request, der einen Exit-Standort angibt (exitState, exitCity, exitAsn, exitOs oder exitLifetimeMin, mit exitClass: premium), läuft ausschließlich über Premium-Exits. Wenn FourA dafür keinen Premium-Exit mehr zum Testen hat, bricht der Aufruf mit "error": "No premium exit answered for this request" und demselben code: no_eligible_proxy ab.

Lösung: Behalte den angeforderten Scope bei und versuche es später erneut. Der Pool wird etwa alle zehn Minuten aktualisiert, sodass ein Land ohne Treffer oft innerhalb einer Stunde wieder verfügbar ist.

import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")

Erweitere die Länderliste nur, wenn sich die Länderanforderung deines Workflows tatsächlich geändert hat. Stille Fallbacks auf andere Länder können nachgelagerte, ortsabhängige Logik beschädigen.

Ein Browser-Profil wird abgelehnt

Symptom: Der Aufruf schlägt mit unknown profile '<id>', no profile matches browser=... oder browser profile selection requires unblocker:true fehl.

Ursache: Der/das von dir übermittelte profile, browser, os oder version ist nicht im Katalog vorhanden, oder du hast eines mit unblocker: false gesendet.

Lösung: Lies GET /api/profiles für den aktuellen Katalog, wähle daraus und behalte unblocker bei, wenn du einen Browser auswählst.

Response-Body enthält unleserlichen Text

Symptom: Der Response-data (oder body) enthält Zeichensalat oder unlesbare Zeichen, wenn das Ziel ein Nicht-UTF-8-Charset verwendet.

Ursache: Standardmäßig dekodiert FourA Response-Bodies automatisch nach UTF-8, basierend auf dem Content-Type-Header des Ziels oder einem HTML-<meta charset>-Tag. Wenn das Ziel falsche Angaben zu seinem Charset macht, erhältst du unleserlichen Text.

Lösung: Setze für binäre Payloads (Bilder, Protobuf, Roh-Audio) returnBuffer: true im Request. Single und Proxy geben data dann als ein Objekt zurück, das die rohen Bytes {"type": "Buffer", "data": [<byte values>]} enthält, ohne dass eine Charset-Transkodierung angewendet wird.

{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}

Dekodiere die Rohdaten bei Textzielen selbst, wenn diese ihr Charset falsch deklarieren: Rufe die Daten mit returnBuffer: true ab, lies die Bytewerte in data.data aus und dekodiere sie anschliessend mit dem korrekten Charset.

Unerwartetes HTML statt JSON

Symptom: Du hast JSON von der Zielseite erwartet, aber HTML erhalten.

Ursache: Die Zielseite liefert je nach Headers moeglicherweise unterschiedliche Inhalte aus.

Loesung: Fuege einen Accept-Header hinzu und aktiviere unblocker fuer realistische Browser-Headers:

curl -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://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

Du kannst tryJsonData auch auf true setzen, damit FourA JSON-Responses automatisch parst.

Der Body ist eine Challenge-Seite, kein Inhalt

Symptom: Der Aufruf war erfolgreich, status ist 200, aber data (oder body) ist eine Bot-Prüfung statt der gewünschten Seite.

Ursache: Das Ziel hat eine Bot-Prüfung durchgeführt, auf die FourA gestoßen ist, die FourA aber nicht lösen konnte. Die Response zeigt das an: Single und Proxy geben defense mit solved: false zurück, und Browser gibt defenseSolved: false mit dem Vendor in defenses.present zurück.

Lösung: Prüfe zuerst defense.vendor, dann eskaliere. Probiere ein anderes Browser-Profil bei Single, wechsle zu Proxy für einen anderen Exit, oder nutze Browser, damit JavaScript ausgeführt wird. Vollständige Feld-Referenz und Vendor-Liste: Site checks.

Füge einen validate.data.accept-Substring hinzu, den nur die echte Seite enthält. Eine Challenge-Seite, die FourA erkennt, gilt nie als Erfolg: Sie wird mit einem X-FourA-Check-Page-Header zurückgegeben und nicht abgerechnet. Ohne validate zählt eine von FourA nicht erkannte Challenge-Seite mit HTTP 200 als Erfolg, und du bemerkst es erst nachgelagert statt direkt beim Aufruf.

Immer noch blockiert?

Wenn keine der obigen Lösungen funktioniert:

  1. Prüfe die Statusseite auf aktuelle Vorfälle
  2. Sieh dir deine Request-Metriken im Dashboard an
  3. Kontaktiere den Support unter support@foura.ai mit deinen Request-Details (gib die X-FourA-Request-Id der fehlgeschlagenen Response an)

Nächste Schritte

Aktualisiert: 13. November 2026