Docs › Fehlerbehebung › Häufige Probleme

Häufige Probleme

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

Leerer oder unvollständiger Inhalt

Symptom: Die API gibt den Status 200 zurück, aber das Feld data ist leer oder es fehlt der erwartete Inhalt.

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

Lösung: Wechsle vom Single-Endpunkt zum Browser-Endpunkt. Verwende checkText, um zu überprü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 CAPTCHA-Seiten

Symptom: Die API gibt HTML mit einer CAPTCHA-Aufforderung oder einer Seite mit verweigertem Zugriff zurück.

Ursache: Die Zielseite hat den request als automatisiert erkannt und blockiert.

Lösung: Nutze den proxy-endpoint für die 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
    }
  }'

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

Timeout-Fehler

Symptom: Requests schlagen mit einem Timeout-Fehler fehl.

Ursache: Die Zielseite lädt länger 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
  }'

Überprüfe bei Browser-Requests außerdem, ob dein checkText-Wert tatsächlich auf der Seite erscheint. Ein Tippfehler führt immer zu einem Timeout.

429 Too Many Requests (RPM-Limit)

Symptom: Die API gibt den Status 429 mit einer "rate limit exceeded"-Meldung zurück.

Ursache: Du hast dein Requests-per-Minute-Limit (RPM) überschritten. Dies unterscheidet sich von Concurrency-Limits (siehe 503 unten).

Lösung: Nutze das Feld retryAfter aus der Response, um vor einem erneuten Versuch die richtige Zeitspanne abzuwarten:

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

Prüfe deine aktuelle Nutzung im Dashboard, um deine Rate Limits zu sehen.

503 Service Unavailable

Symptom: API gibt den Status 503 zurück.

Ursache: Dies passiert in zwei Fällen:

  1. Concurrency-Limit erreicht. Du hast zu viele gleichzeitige Requests am Laufen. Dies unterscheidet sich von 429, was die Requests pro Minute limitiert. Bei 503 hast du deine RPM nicht überschritten, aber das Maximum an gleichzeitig laufenden Requests erreicht.
  2. Service vorübergehend deaktiviert. Ein Wartungsfenster ist aktiv.

Beide Fälle enthalten ein retryAfter-Feld in der Response.

Lösung: Warte retryAfter Sekunden und versuche es dann erneut:

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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Wenn du regelmäßig 503-Concurrency-Limits erreichst, reduziere die Anzahl paralleler Requests in deiner Scraping-Pipeline oder überprüfe das Concurrency-Limit deines Plans im Dashboard.

504 Upstream Timeout

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

Ursache: Die Arbeit wurde nicht innerhalb des für den Request deklarierten Zeitbudgets abgeschlossen. Ein langsames Ziel, das Lösen einer kalten Challenge oder eine sehr große Seite können dies verursachen. Es liegt nicht an deinem Key, deinen Parametern oder deinem Proxy.

Lösung: Gib dem Aufruf mehr Zeit oder versuche es erneut. FourA wartet auf dein timeout_ms plus einen kleinen Puffer, 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 kalter erster Aufruf mehrere zehn Sekunden dauern. Sein timeout_ms deckt die gesamte Leiter ab und akzeptiert bis zu 180000.

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 hat seine eigene Engine erreicht, konnte die Antwort aber nicht verwenden, meist wegen eines Neustarts der Instanz.

Lösung: Versuche es mit einem kurzen Backoff erneut. Beide werden als service_error klassifiziert, und nur success wird berechnet. Ein erneuter Versuch kostet dich also nicht extra. Wenn es länger als ein oder zwei Minuten dauert, prüfe die Statusseite.

401 Authentifizierungsfehler

Symptom: Jeder Request gibt 401 Unauthorized zurück.

Checkliste:

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

400 Ziel verweist auf private/reservierte IP

Symptom: Die API gibt 400 mit Target <ip> resolves to a private/reserved IP zurück, bevor der Request FourA verlässt.

Ursache: Dein url wird in einen privaten, Loopback- oder reservierten IP-Bereich (RFC 5735, RFC 6598 oder reservierte IPv6-Blöcke) aufgelöst. FourA lehnt diese Ziele ab, damit sein Netzwerk nicht zum Erreichen interner Hosts verwendet werden kann.

Lösung: Rufe eine öffentliche URL ab. Wenn du testest, verwende ein öffentliches Ziel wie https://example.com oder https://httpbin.org/get. Wenn das gewünschte Ziel ein von dir betriebener Dienst ist, stelle ihn zuerst unter einem öffentlichen Hostnamen bereit.

{ "error": "Target <ip> resolves to a private/reserved IP" }

no_eligible_proxy bei Verwendung von exitCountries

Symptom: Ein /api/proxy/ Aufruf mit exitCountries gibt HTTP 200 mit einem JSON-Fehlerobjekt 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 für das Ziel sichtbares Land mit deiner Allowlist übereinstimmt. FourA weicht nie auf ein nicht angefordertes Land aus, wenn du exitCountries setzt.

Lösung: Behalte den angeforderten Bereich bei und versuche es später erneut. Der Pool wird etwa alle zehn Minuten aktualisiert, sodass ein Land ohne aktuellen Treffer oft innerhalb einer Stunde einen erhält.

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 wirklich geändert hat. Stille Fallbacks auf andere Länder können nachgelagerte geo-abhängige Logik beschädigen.

Response Body wird als unleserlicher Text zurückgegeben

Symptom: Die Response data (oder body) enthält Mojibake oder unleserliche 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, Raw Audio) returnBuffer: true im Request. Der Body wird als Base64-Buffer ohne Charset-Transcoding zurückgegeben.

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

Für Textziele, die ihr Charset falsch angeben, dekodiere die rohen Bytes selbst: Rufe mit returnBuffer: true ab, dekodiere Base64, wende dann das richtige Charset an.

Unerwartetes HTML statt JSON

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

Ursache: Die Zielseite liefert möglicherweise je nach Headern unterschiedliche Inhalte aus.

Lösung: Füge einen Accept-Header hinzu und aktiviere unblocker für realistische Browser-Header:

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 auch tryJsonData 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 ein Bot-Check anstelle der gewünschten Seite.

Ursache: Das Ziel führte einen Bot-Check durch, auf den FourA stieß, ihn aber nicht lösen konnte. Die Response zeigt dies: Single und Proxy geben defense mit solved: false zurück, und Browser gibt defenseSolved: false mit dem Anbieter in defenses.present zurück.

Lösung: Prüfe zuerst defense.vendor, eskaliere dann. Versuche ein anderes Browser-Profil bei Single, wechsle zu Proxy für einen anderen Exit, oder nutze Browser, damit JavaScript ausgeführt wird. Vollständige Feldreferenz und Anbieterliste: Anti-Bot Defenses.

Füge einen validate.data.accept Substring hinzu, den nur die echte Seite enthält. Ohne diesen zählt eine mit HTTP 200 zurückgegebene Challenge-Seite als Erfolg, und du merkst es erst später anstatt direkt beim Aufruf.

Immer noch Probleme?

Wenn keine der obigen Lösungen funktioniert:

  1. Prüfe die Statusseite auf laufende Vorfälle
  2. Überprüfe deine Request-Metriken im Dashboard
  3. Kontaktiere den Support unter support@foura.ai mit deinen Request-Details (füge X-FourA-Request-Id aus der fehlgeschlagenen Response bei)

Nächste Schritte

Aktualisiert: 12. August 2026