# Häufige Probleme

> URL: https://foura.ai/de/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

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:

```bash
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:

```bash
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](#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):

```bash
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.

```json
{
  "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](https://foura.ai/docs/api/endpoints#exit-location) 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](https://foura.ai/docs/dashboard/quota) 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:

```python
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](https://foura.ai/docs/how-to/run-requests-in-parallel) beschreibt das Muster, und **Nutzung & Limits** im [Dashboard](https://foura.ai/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:

```python
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:

```json
{
  "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](https://updates.foura.ai/status).

## 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](https://foura.ai/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](https://foura.ai/docs/api/endpoints) 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.

```json
{ "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](https://foura.ai/docs/api/inspect) (`/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:

```json
{
  "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.

```python
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`](https://foura.ai/docs/api/endpoints#browser-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.

```json
{
  "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:

```bash
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](https://foura.ai/docs/api/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](https://updates.foura.ai/status) auf aktuelle Vorfälle
2. Sieh dir deine Request-Metriken im [Dashboard](https://foura.ai/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

- [Error Handling](https://foura.ai/docs/api/errors): Referenz der API-Fehlercodes
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Alle Tarif- und Plattform-Limits mit Feldern
- [Request Outcomes](https://foura.ai/docs/api/outcomes): Wie Outcomes das Geschehene klassifizieren
- [Site checks](https://foura.ai/docs/api/site-checks): Was das Feld `defense` aussagt
- [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type): Wähle den besten Ansatz für dein Ziel
- [Dashboard Overview](https://foura.ai/docs/dashboard/overview): Überwache deine Requests
