# API-Endpoints-Referenz

> URL: https://foura.ai/de/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Eine Referenz für alle FourA API-Endpoints mit Request-Parametern und Response-Formaten.

## Basis-URL

```
https://eu.api.foura.ai/api
```

## Authentifizierung

Jeder Request erfordert deinen API-Key im Header `X-API-Key`:

```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://example.com"}'
```

Erstelle und verwalte API-Keys im [Dashboard](https://foura.ai/dashboard). Keys verwenden das Präfix `pk_live_`.

## Response-Header

Responses von `/api/*` enthalten zwei Korrelations-Header:

| Header | Value | Description |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | Eindeutige ID, die dem Request zugewiesen wird. Wird bei jeder Response zurückgegeben, einschließlich 4xx und 5xx, außer bei einem Body, den FourA überhaupt nicht lesen kann: `400 Invalid JSON in request body` und `413` werden abgelehnt, bevor eine ID zugewiesen wird. Protokolliere sie auf deiner Seite. |
| `X-FourA-Credits` | integer | Für diesen Request verbrauchte Credits. Wird bei jeder Response zurückgegeben, die eine Engine erreicht hat, unabhängig von Erfolg oder Misserfolg (die Arbeit wurde in beiden Fällen ausgeführt). Ein Aufruf, den FourA abgelehnt hat, bevor eine Engine ihn ausgeführt hat (ein fehlender oder ungültiger Key, ein Plan- oder Plattform-Limit, eine abgelehnte Ziel- oder Proxy-ID), enthält keinen. Unter [Request-Ergebnisse](https://foura.ai/docs/api/outcomes) erfährst du, welche Ergebnisse abrechenbar sind. |

Dieselbe Request-ID dient als Schlüssel für die Vorschau der Request- und Response-Payloads im [Aktivitätsprotokoll](https://foura.ai/docs/dashboard/activity-log) des Dashboards (24 Stunden aufbewahrt, die letzten 200 pro Key). So kannst du den genauen Request später nachschlagen und direkt aus der Aktivität im [Playground](https://foura.ai/docs/dashboard/playground) erneut ausführen. Gib sie an, wenn du den Support kontaktierst, damit der Request sekundenschnell gefunden werden kann.

```bash
$ curl -i -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://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...
```

Siehe [Response Headers](https://foura.ai/docs/api/response-headers) für die vollständige Liste und Nutzungstipps.

## Endpoints

> **Nutzung dieser Endpoints via MCP?** Der [`@fouradata/mcp` Server](https://foura.ai/docs/mcp/server) kapselt alle vier Endpoints als native MCP-Tools (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) mit denselben Eingabeformaten plus einem `offload_large` Opt-in für token-effizientes Handling großer Responses. Die Unterschiede: `foura_browser` hat kein `lean`-Feld und `foura_proxy` akzeptiert die [exit location](#exit-location)-Felder derzeit noch nicht.

FourA bietet vier Request-Endpoints, jeweils optimiert für ein bestimmtes Szenario:

| Endpoint | Ideal für |
|----------|----------|
| `POST /auto/` | Smart Fetch. Du übergibst eine URL, FourA wählt den günstigsten funktionierenden Pfad (rotierter Proxy oder Browser, plus ein direkter Request mit `forceProxy: false`) und merkt sich pro Host, was funktioniert. |
| `POST /single/` | Schnelle HTTP-Requests, statische Seiten, APIs |
| `POST /proxy/` | Geschützte Seiten mit automatischer Proxy-Rotation, optionales Länderscoped Routing |
| `POST /browser/` | JavaScript-gerenderte Seiten, SPAs |
| `GET /profiles` | Der Browser-Profil-Katalog für `single` und `proxy`. Öffentlich, kein API-Key erforderlich. |

Einen detaillierten Leitfaden zur Auswahl findest du unter [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type) und im [Smart Fetch guide](https://foura.ai/docs/guides/smart-fetch).

## Target-URL-Einschränkungen

Ziele, die zu privaten, Loopback- oder reservierten IP-Bereichen auflösen (RFC 5735, RFC 6598, IPv6-reservierte Blöcke), werden mit einem 400 abgelehnt, bevor der Request FourA verlässt. Nur öffentliche Hostnames und IPs werden weitergeleitet.

```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 Ziel auf FourAs eigenem API-Host (`eu.api.foura.ai` oder `api.foura.ai`) wird auf allen vier Endpoints ebenfalls mit einem 400 abgewiesen, bevor Daten abgerufen oder abgerechnet werden. Eine URL mit einem Leerzeichen oder Steuerzeichen darin wird bei Single, Proxy und Auto genauso mit einem 400 abgewiesen; kodiere das Leerzeichen als `%20` (Browser ruft es so ab wie Chrome). Die einzige Seite dort, die FourA abruft, ist [`/inspect`](https://foura.ai/docs/api/inspect).

```json
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
```

---

## Smart Fetch (Auto)

`POST /api/auto/`

Du übergibst eine URL sowie optionale `validate`-Regeln. FourA durchläuft eine kostenbewusste Eskalationsstufe (rotierender Proxy, dann vollständiger Browser) und stoppt bei der ersten Stufe, die eine Antwort liefert, die deine Regeln akzeptieren. Mit `forceProxy: false` wird zuerst ein günstiger direkter Test ausgeführt. Bei wiederholten Aufrufen desselben Hosts wird stattdessen eine bestehende Session wiederverwendet, sodass der zweite Abruf günstig ist.

Du musst Retries, Pool-Größen oder Proxy-Zahlen nicht manuell anpassen. FourA lernt sie pro Host.

### Request-Body

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|-----------|------|----------|---------|-------------|
| `url` | string | Ja | - | Ziel-URL |
| `method` | string | Nein | `"GET"` | HTTP-Methode |
| `headers` | [string, string][] | Nein | - | An das Ziel zu sendende Header als [name, value]-Paare. Jede Stufe außer einer Browser-Stufe sendet sie. Ein von dir gesendeter `Cookie` erreicht die Website unverändert, und Cookies einer gespeicherten Session werden nur unter Namen ergänzt, die du nicht gesendet hast. Der `userAgent` einer gespeicherten Session ersetzt deinen `User-Agent`. Die Proxy-Stufe lässt bedingte Header wie `If-None-Match` aus, es sei denn, dein `validate.status.accept` führt `304` auf. |
| `data` | any | Nein | - | Request-Body für Nicht-GET-Requests |
| `validate` | object | Nein | - | Erfolgskriterien, gleiches Format wie `validate` von Single Request (siehe unten). Gib dem Auto-Modus vor, wie eine echte Seite aussieht, damit er Content von einer Challenge-Seite unterscheiden kann. |
| `returnSession` | boolean | Nein | `true` | Enthält die erfolgreiche Session (`proxy`, `cookies`, `userAgent`) in der Response, damit du sie über `/api/single/` oder `/api/browser/` wiederverwenden kannst. |
| `forceProxy` | boolean | Nein | `true` | Immer über einen rotierenden Proxy routen. Setze `false`, um den günstigeren direkten Pfad zu erlauben, wenn das Ziel dies zulässt (einige Schutzmechanismen reagieren strenger auf Proxy-Traffic). |
| `timeout_ms` | integer | Nein | `120000` | Gesamtes Zeitbudget für den gesamten Aufruf in Millisekunden. Alle Teilversuche laufen innerhalb dieses Budgets. Min `5000`, Max `180000`. |
| `ignoreProxies` | string[] | Nein | - | Proxy-IDs, die bei jedem Teilversuch vermieden werden sollen. Verwende IDs aus vorherigen `/api/auto/`- oder `/api/proxy/`-Responses. |
| `followRedirects` | integer | Nein | `5` | Maximale Anzahl an Redirects, denen auf den günstigen Stufen gefolgt wird. `0` zum Deaktivieren. Max `20`. |
| `exitClass` | string | Nein | - | `standard` oder `premium`, wie bei [Proxy Request](#exitclass). Mit `premium` kann der Aufruf auf einen Premium-Exit eskalieren, sobald der Standard-Pool die Seite nicht erreichen kann. Erfordert einen Plan mit Premium-Exits. Siehe [exitClass on Smart Fetch](#exitclass-on-smart-fetch). |

### Response

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `status` | number | HTTP-Status des Ziels. |
| `data` | string | Response-Body als Text, unabhängig von der ausliefernden Stufe. Eine JSON-Seite wird als JSON-Text zurückgegeben, du parst sie also selbst. |
| `headers` | array oder object | Response-Header des Ziels. Single- und Proxy-Stufen liefern ein Array von Hop-spezifischen Header-Objekten zurück; Browser-Stufen liefern ein flaches Objekt. |
| `meta.rung` | string | Welche Stufe der Kette die Response geliefert hat. Mögliche Werte: `probe` (günstiger direkter Request, nur mit `forceProxy: false`), `proxy` (rotierender Proxy), `browser` (vollständiges Browser-Rendering), `cache` (wiederverwendete warme Session), `warmup` (Startseite der Website wurde zuerst geladen und ihre Cookies öffneten die Deep-URL) oder `fail` (keine Stufe erzeugte eine akzeptierte Response). |
| `meta.solved` | boolean | Gibt an, ob die Seite einen zusätzlichen Schritt erforderte (Challenge-Seite) und dieser während dieses Aufrufs abgeschlossen wurde. |
| `meta.attempts` | number | Vor dem Erfolg durchgeführte Unterversuche. |
| `meta.credits` | number | Für diesen Aufruf verbrauchte Gesamtkredits. Entspricht `X-FourA-Credits`. |
| `meta.attemptsByEngine` | object | An `single`, `proxy` und `browser` gesendete Requests. Ein Browser-Request, den dein Plan abgelehnt hat, zählt mit, da er gesendet wurde. |
| `meta.browserRequests` | number | Browser-Requests, die einen Slot deines Tageskontingents verbraucht haben. Ein vom Plan abgelehnter Browser-Request verbraucht nichts. |
| `meta.exitClass` | string | Ausliefernde Exit-Klasse, vorhanden wenn im Request `exitClass` angegeben wurde: `premium` oder `standard`. Derselbe Wert wird im `X-FourA-Exit-Class` Response-Header übertragen. |
| `session.proxy` | string | Codierte ID des Proxys, der die Response geliefert hat. Wiederverwendbar für einen Single- oder Browser-Request. Vorhanden, wenn `returnSession` gleich `true` ist. |
| `session.cookies` | array | Cookies zur Wiederverwendung, jeweils mit mindestens `name` und `value`. Eine Browser-Stufe gibt den Cookie-Jar des Browsers zurück. Eine Proxy-Stufe oder der direkte Test liefert nur die Cookies zurück, die die Seite geöffnet haben (etwa jene von einer Challenge-Seite), nie alle von der Seite gesetzten Cookies; die Liste kann daher leer sein. Vorhanden, wenn `returnSession` gleich `true` ist. |
| `session.userAgent` | string | Beim erfolgreichen Versuch verwendeter User-Agent. Vorhanden, wenn `returnSession` gleich `true` ist. |
| `error` | string | Fehlermeldung bei fehlgeschlagenem Aufruf. |
| `attemptReport` | object | Bei fehlgeschlagenem Aufruf: Engine-Requests ohne gelieferte Seite, aufgeschlüsselt nach Ursache. Siehe [Smart Fetch](https://foura.ai/docs/guides/smart-fetch). |

### Beispiel

```bash
curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'
```

### Hinweise

- Auto fungiert als Koordinator. Es ruft intern Single, Proxy oder Browser auf und leitet deinen API-Key an jeden Sub-Call weiter. Der Auto-Aufruf zählt als ein Request in deinem [Activity Log](https://foura.ai/docs/dashboard/activity-log) und in deiner Overview, mit der Summe der Credits seiner Sub-Calls. Die Sub-Calls werden darunter als Versuche aufgelistet und zählen nie als eigene Requests.
- Übergib `validate.data.accept` mit einem Substring, den nur die echte Seite enthält. Ohne diesen Parameter kann Auto ein echtes 200-Ergebnis nicht von einer Challenge-Zwischenseite unterscheiden, die mit Status 200 zurückgegeben wird.
- Eine entfernte Seite ist die Antwort der Website, keine Verweigerung. Wenn zwei Exits denselben `404` oder `410` zurückgeben und dein `validate` ihn nicht akzeptiert, endet der Aufruf mit diesem `status` sowie einem `error`, der mit `the site answered` beginnt. Trage den Status in `validate.status.accept` ein, und Auto liefert die erste Response mit diesem Status, die den Rest deiner `validate` besteht. Dasselbe gilt für jeden anderen Status, den du dort auflistest, außer `403`, `429`, `503` und `202`, die Websites ebenfalls zusammen mit einer Challenge-Seite senden.
- `timeout_ms` begrenzt den gesamten Aufruf. Ein erster kalter Zugriff auf eine geschützte Website kann mehrere zehn Sekunden dauern. Wiederverwendete warme Sessions sind meist in unter einer Sekunde abgeschlossen.

### exitClass bei Smart Fetch

`exitClass` funktioniert bei Smart Fetch genauso wie bei [Proxy Request](#exitclass): als Freigabe, nicht als Anweisung. Auto versucht es zuerst über den Standard-Pool. Wenn der Standard-Pool die Seite nicht erreichen kann und der Request `premium` angibt, öffnet Auto die Seite in einem Browser über einen Premium-Exit. Die dort aufgebaute Session bedient deine späteren Aufrufe derselben Website, die ebenfalls `premium` angeben. Aufrufe, die dies nicht angeben, verwenden sie nie.

Das Aufbrauchen des Kontingents ist kein Fehler. Sobald der Premium-Traffic deines Tarifs für den Abrechnungszeitraum aufgebraucht ist, wird der Aufruf im Standard-Pool fortgesetzt und `meta.exitClass` liefert `standard`. In einem Tarif ohne Premium-Exits wird ein Aufruf mit `exitClass: premium` über einen `403` mit `X-FourA-Limit: plan_limit_premium` abgelehnt, bevor Arbeit anfällt.

Premium-Traffic wird wie beim Proxy Request gemessen. Eine in einem Browser geöffnete Seite lädt mehr als nur die reine Seite selbst, daher verbraucht eine Premium-Smart-Fetch-Seite mehr Premium-Traffic als dieselbe über Proxy Request geladene Seite. Um diesen Verbrauch gering zu halten, lädt eine Premium-Smart-Fetch-Seite keine Bilder, Schriftarten und Mediendateien sowie keine Skripte bekannter Werbe-, Analyse- und Consent-Anbieter.

---

## Single Request

`POST /api/single/`

Sendet einen HTTP-Request mit realistischen, browserähnlichen Wire-Eigenschaften, ohne einen echten Browser zu starten. Dies ist der schnellste Endpoint.

### Request Body

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|-----------|------|----------|---------|-------------|
| `method` | string | Ja | - | HTTP-Methode: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | Ja | - | Ziel-URL. Verwende `{ts}` an beliebiger Stelle in der URL, um den aktuellen Zeitstempel für Cache-Busting einzufügen. |
| `headers` | [string, string][] | Nein | - | Benutzerdefinierte Header als [name, value]-Paare |
| `unblocker` | boolean | Nein | `true` | Realistische Browser-Header senden (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Standardmäßig aktiviert. Wenn du `false` setzt, fügt FourA keine Browser-Header hinzu, sondern nur die von dir übergebenen. |
| `timeout_ms` | number | Nein | 15000 | Gesamter Timeout in ms (max: 120000) |
| `connect_timeout_ms` | number | Nein | 5000 | Verbindungs-Timeout in ms |
| `accept_timeout_ms` | number | Nein | 5000 | Accept-Timeout in ms (Wartezeit auf Verbindungsannahme) |
| `server_response_timeout_ms` | number | Nein | 15000 | Server-Antwort-Timeout in ms (Wartezeit auf das erste Byte) |
| `dns_cache_timeout_sec` | number | Nein | 120 | DNS-Cache-TTL in Sekunden (max: 240) |
| `followRedirects` | number | Nein | disabled | Maximale Anzahl an Weiterleitungen (0-20). Weglassen zum Deaktivieren. |
| `tryJsonData` | boolean | Nein | false | Response-Body nach Möglichkeit als JSON parsen |
| `returnBuffer` | boolean | Nein | false | Rohen Buffer statt decodierten String zurückgeben |
| `data` | any | Nein | - | Request-Body (String oder Objekt, automatisch zu JSON serialisiert) |
| `proxy` | string | Nein | - | Proxy-ID aus einer früheren Response, um denselben Exit-Knoten festzuhalten. Übergib den opaken String unverändert zurück. Eine reine Proxy-Adresse wird mit `400 Invalid proxy format` abgelehnt. Manche IDs können nicht festgehalten werden: siehe [Pinning an exit](#pinning-an-exit). |
| `browser` | string | Nein | Chrome | Vorzutäuschender Browser: Chrome, Edge, Safari, Firefox oder Tor. Siehe [Browser profiles](#browser-profiles). |
| `os` | string | Nein | - | Vorzutäuschendes Betriebssystem: Windows, macOS, Android oder iOS. Ein Familienname akzeptiert jede seiner Versionen. |
| `version` | string | Nein | newest | Vorzutäuschende Browser-Version laut Katalog. Bei mehreren Treffern gewinnt die neueste Version. |
| `profile` | string | Nein | - | Exakte Profil-ID aus `GET /api/profiles` anstelle der drei obigen Felder. |
| `validate` | object | Nein | - | Validierungsregeln für Antworten (siehe unten) |

### Browser-Profile

Standardmäßig verwendet ein Request das neueste Google Chrome. Manche Ziele akzeptieren einen bestimmten Browser und blockieren andere. Daher grenzen `browser`, `os` und `version` einen Katalog vermessener Profile ein, und `profile` wählt ein Profil direkt per ID aus.

```json
{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}
```

Regeln:

- Die Auswahl erfordert `unblocker` (standardmäßig aktiviert). Wenn `unblocker` deaktiviert ist, werden keine Browser-Header gesendet, sodass der Request abgelehnt wird, anstatt ihn nur teilweise anzuwenden.
- Wenn mehrere Profile übereinstimmen, gewinnt die neueste Version.
- Eine Kombination, die der Katalog nicht bereitstellen kann, gibt einen Fehler zurück, der die verfügbaren Optionen nennt. Eine unbekannte `profile`-ID gibt `unknown profile '<id>'` zurück. Der Request wird niemals als anderer Browser gesendet.
- Dieselben vier Felder sind im `request`-Objekt von `POST /proxy/` verfügbar.

`GET /api/profiles` gibt den vollständigen Katalog zurück und benötigt keinen API-Key:

```json
{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}
```

`osFamily` ist der Wert zum Filtern beim Erstellen einer Auswahlliste; `os` behält den Release-Namen für die Anzeige bei.

### Validierungsregeln

Mit dem Objekt `validate` kannst du Bedingungen für Erfolg und Fehlschlag definieren. Wenn eine `fail`-Bedingung zutrifft, wird der Request als fehlgeschlagen behandelt. Wenn `accept`-Bedingungen festgelegt sind, werden nur übereinstimmende Responses als erfolgreich behandelt.

```json
{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `validate.status.accept` | number[] | Zu akzeptierende HTTP-Statuscodes |
| `validate.status.fail` | number[] | Abzulehnende HTTP-Statuscodes |
| `validate.headers.accept` | object | Die Response ist erfolgreich, wenn mindestens ein Paar bei einem beliebigen Redirect-Hop übereinstimmt. Namen und Werte werden unabhängig von Groß- und Kleinschreibung als Teilstring abgeglichen. |
| `validate.headers.fail` | object | Header-Schlüssel-Wert-Paare, die einen Fehler auslösen |
| `validate.data.accept` | string[] | Die Response ist erfolgreich, wenn der Body mindestens einen dieser Strings enthält |
| `validate.data.fail` | string[] | Strings im Response-Body, die einen Fehler auslösen |

### Beispiel

```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://example.com/products",
    "timeout_ms": 10000
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}
```

Führt das Ziel vor der Auslieferung des Body einen Bot-Check durch, enthält die Response zusätzlich ein `defense`-Objekt mit Angaben zum Anbieter und dazu, ob der Check bestanden wurde:

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

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `status` | number | HTTP-Statuscode des Ziels |
| `headers` | array | Ein Objekt pro Redirect-Hop. Jedes enthält ein Feld `result` mit der Statuszeile und allen Response-Headern. Multi-Value-Header (`Set-Cookie`, `Link`, `WWW-Authenticate`) werden als String-Arrays zurückgegeben. |
| `data` | string/object | Response-Body (JSON, falls `tryJsonData` true ist) |
| `total_time` | number | Gesamte Request-Dauer in Sekunden |
| `proxy` | string | Enkodierte ID des verwendeten Proxys (nur wenn `proxy` im Request übergeben wurde). Verwende sie bei Folgeaufrufen erneut, um denselben Exit-Knoten festzuhalten. |
| `defense` | object | Vorhanden, wenn das Ziel bei diesem Request eine Bot-Prüfung durchgeführt hat oder wenn ein Retry mit den Cookies der Website den Body geliefert hat. `defense.solved` gibt an, ob eine Prüfung bestanden wurde, `defense.retry` gibt an, ob ein Retry den Inhalt geliefert hat. Siehe [Site checks](https://foura.ai/docs/api/site-checks) für alle Felder und die vollständige Liste der Systeme. |
| `error` | string | Fehlermeldung, falls der Request fehlgeschlagen ist |

---

## Proxy Request

`POST /api/proxy/`

Leitet deinen Request über rotierende Proxys mit automatischem Retry bei Fehlern weiter. Optional kannst du die Auswahl auf bestimmte, für das Ziel sichtbare Exit-Länder einschränken.

### Request-Body

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|-----------|------|----------|---------|-------------|
| `request` | object | Ja | - | Ein einzelner Request-Body (gleiche Felder wie bei Single Request oben) |
| `timeout_ms` | number | Nein | 45000 | Gesamtes Timeout fuer alle Versuche in ms (max: 120000) |
| `maxTries` | number | Nein | 5 | FourA startet keine neuen Versuche mehr, sobald so viele fehlgeschlagen sind (max: 90). Versuche laufen parallel, daher koennen etwas mehr als diese Anzahl abschliessen. |
| `ignoreProxies` | string[] | Nein | - | Proxy-IDs, die von der Rotation ausgeschlossen werden sollen (nutze IDs aus frueheren Responses) |
| `exitCountries` | string[] | Nein | - | Strikte Allowlist aus zweistelligen, fuer das Ziel sichtbaren Laendercodes (z. B. `["CZ", "GB"]`). Werte werden getrimmt, in Grossbuchstaben umgewandelt und dedupliziert. Exits im Standard-Pool mit unbekanntem Land werden ausgeschlossen, und der Standard-Pool faellt nie auf ein nicht angefordertes Land zurueck. Ein Premium-Exit erfolgt ebenfalls ueber eines der aufgefuehrten Laender. |
| `exitClass` | string | Nein | - | `standard` oder `premium`. `premium` erlaubt die Eskalation des Requests auf einen Premium-Exit, wenn der Standard-Pool bei einem geschuetzten Ziel Probleme hat. Erfordert einen Plan mit Premium-Exits. |
| `exitState` | string | Nein | - | Region, aus der der Exit erfolgt. Erfordert `exitClass: premium` und genau ein Land in `exitCountries`. Siehe [Exit location](#exit-location). |
| `exitCity` | string | Nein | - | Stadt, aus der der Exit erfolgt. Erfordert `exitClass: premium` und genau ein Land in `exitCountries`. |
| `exitAsn` | string | Nein | - | Netzwerk, aus dem der Exit erfolgt, nach AS-Nummer, zum Beispiel `8866`. Erfordert `exitClass: premium` und genau ein Land in `exitCountries`. |
| `exitOs` | string | Nein | - | `windows`, `android`, `ios` oder `mac`: der Geraetetyp, zu dem die Adresse gehoert. Erfordert `exitClass: premium`. |
| `exitLifetimeMin` | integer | Nein | - | Minuten, die der Exit seine Adresse behaelt, `3` bis `1440`. Erfordert `exitClass: premium`. |

### exitCountries Scoping

Die Auswahl nutzt die neuesten verfuegbaren, fuer das Ziel sichtbaren Laender-Metadaten, die normalerweise innerhalb von etwa zehn Minuten aktualisiert werden. Es handelt sich nicht um einen Live-Geolocations-Lookup waehrend des Requests. Leite das bereitstellende Land nicht aus der Proxy-Host-Adresse ab.

Wenn der aktuelle Pool keine Uebereinstimmung fuer die angeforderten Laender hat und der Request `exitClass: premium` nicht angegeben hat, gibt die Response HTTP 200 mit einem Error-Envelope zurueck:

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

Behalte den angeforderten Scope bei und versuche es später erneut. Ändere oder erweitere ihn nur, wenn sich die Länderanforderung deines Workflows explizit ändert.

### Beispiel

```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": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `proxy` | string | Codierter Bezeichner des verwendeten Proxys. Verwende ihn bei einem Single- oder Browser-Request wieder, indem du ihn als `proxy`-Feld übergibst, oder überspringe ihn beim nächsten Proxy-Request via `ignoreProxies`. |
| `exitCountry` | string | Zwei-Buchstaben-Ländercode (zielseitig sichtbar) des Proxys, der den Request verarbeitet hat. Nur vorhanden, wenn der Request `exitCountries` gesetzt hat, unabhängig von der bedienenden Exit-Klasse. Prüfe vor Weiterverarbeitung der Antwort immer, ob es sich um einen der von dir angeforderten Codes handelt. |
| `exitClass` | string | Gibt an, welche Exit-Klasse diesen Request bedient hat; vorhanden bei einer erfolgreichen Antwort, wenn der Request eine bestimmte Klasse vorgegeben hat. `premium` bedeutet, dass ein Premium-Exit den Body zurückgegeben hat; `standard` bedeutet, dass der Standard-Pool verwendet wurde. Ein fehlgeschlagener Aufruf hat nichts ausgeliefert und enthält daher kein `exitClass`; prüfe stattdessen `attemptReport`, um Details zu den Versuchen zu sehen. |
| `total` | number | Gesamtlaufzeit nach Echtzeit in Sekunden (Float). Umfasst Proxy-Auswahl, Retries und den erfolgreichen Versuch. `total_time` misst nur den inneren Request; `total` ist immer >= `total_time`. |
| `profile` | string | Das von der Rotation gewählte Browser-Profil, **nur** vorhanden, wenn es nicht dem von dir angeforderten Profil entspricht. Fehlt der Wert, wurde der Request exakt wie angegeben gesendet. Übergib die ID bei Folgeaufrufen als `profile`, um den funktionierenden Browser beizubehalten. |
| `error` | string | Fehlermeldung, falls der Request fehlgeschlagen ist. Bei einem Scope-Miss lautet `code` `no_eligible_proxy` und `details.exitCountries` gibt den normalisierten Scope zurück. |
| `attemptReport` | object | Vorhanden bei **jedem** fehlgeschlagenen Proxy-Aufruf. Zählt die aufgetretenen Ereignisse der Versuche, damit ein blockierter Pool, ein toter Pool und eine `validate`-Regel ohne Treffer nicht alle denselben Fehler anzeigen. Siehe unten. |
| `request` | object | Vorhanden bei einem fehlgeschlagenen Proxy-Aufruf: Der von FourA ausgeführte Request, inklusive Standardwerten und deinen übergebenen `ignoreProxies`. |

Alle Response-Felder von Single Request sind ebenfalls enthalten, darunter `defense`: Ein Proxy-Versuch, der auf eine Bot-Erkennung trifft, meldet dies genauso wie Single.

### Warum ein Proxy-Aufruf fehlgeschlagen ist

`Download maxTry limit reached` liefert unabhängig vom Ablauf der Versuche das gleiche Ergebnis, daher enthält jede fehlgeschlagene Proxy-Antwort neben dem Fehler ein `attemptReport`:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `total` | integer | Durchgeführte Versuche |
| `noResponse` | integer | Der Exit hat nie geantwortet, die Website wurde also nie erreicht |
| `defense` | integer | Die Website hat geantwortet und in der Antwort wurde ein Bot-Check erkannt |
| `contentRejected` | integer | HTTP 200, kein Bot-Check, nur durch dein `validate.data` abgelehnt |
| `statusRejected` | integer | Die Website hat geantwortet, kein Bot-Check, abgelehnt durch dein `validate.status` |
| `other` | integer | Geantwortet und keines der obigen Kriterien |
| `vendors` | string[] | Bot-Check-Anbieter, die im Task erkannt wurden |
| `profilesTried` | string[] | Vom Task gesendete Browser-Profile in der Reihenfolge der Erstverwendung. `default` bedeutet, dass dein Request unverändert gesendet wurde. |
| `summary` | string | Ein aus den Zählern erstellter Satz, sicher für Logs |

Der `error`-String bleibt unverändert, sodass Clients, die darauf matchen, weiter funktionieren. Was bei jedem Zähler zu tun ist: [Warum ein Proxy-Request keine Versuche mehr hatte](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### exitClass

Manche Ziele blockieren die Exits im Standard-Pool unabhängig von der Anzahl der Versuche. `exitClass: premium` teilt Proxy mit, dass ein solcher Request zusätzlich zum Standard-Pool an einen **Premium-Exit** eskaliert werden darf, anstatt nur innerhalb des Pools zu rotieren.

```json
{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}
```

Drei Dinge solltest du vor dem Senden wissen.

**Es ist ein Kontingent, keine feste Anweisung.** Der Standard-Pool konkurriert weiterhin um die Antwort und gewinnt meist. Ein Premium-Exit schaltet sich erst ein, wenn der Pool ein kurzes Budget fuer den Request aufgebraucht hat oder das Ziel ihn sichtbar abgewiesen hat. Ein Request, den der Standard-Pool beantwortet, bevor ein Premium-Exit versucht wurde, gilt als normaler Erfolg und kostet dich keinen Premium-Traffic. Sobald ein Premium-Exit versucht wurde, zaehlt dessen Traffic, wie unten beschrieben.

**Ein Premium-Exit bleibt innerhalb von `exitCountries`.** Bei einer Laenderliste erfolgt der Premium-Exit ueber eines dieser Laender, und `exitCountry` in der Response gibt dieses an, genau wie beim Standard-Pool.

**Die Response zeigt dir, was die Anfrage tatsaechlich bedient hat.** Wenn du eine Klasse angibst, enthaelt die Response `exitClass`:

```json
{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}
```

`premium` bedeutet, dass ein Premium-Exit den Body zurückgegeben hat. `standard` bedeutet, dass dies der Standard-Pool getan hat. Diese Antwort erhältst du auch, wenn kein Premium-Exit bezogen werden konnte oder wenn der in deinem Tarif enthaltene Premium-Traffic (plus dazugekaufte Kontingente) für den Abrechnungszeitraum aufgebraucht ist. Beides ist kein Fehler, und du kannst deinen Premium-Traffic anhand dieser Werte pro Request statt über eine Monatsgesamtsumme abgleichen. Derselbe Wert wird im `X-FourA-Exit-Class`-Response-Header übertragen (siehe [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**Premium-Traffic wird auf Netzwerkebene gemessen.** Ein Premium-Versuch zählt alle gesendeten und empfangenen Daten bei der Übertragung über das Netzwerk, komprimiert und verschlüsselt wie übertragen, unabhängig davon, ob deine Seite zurückgegeben wurde. Ein Versuch, der noch lief, als ein anderer Exit geantwortet hat, wird sofort abgebrochen, und der bis dahin übertragene Traffic zählt ebenfalls. Premium-Traffic wird auf dein Premium-Kontingent angerechnet und ist gleichzeitig in deiner Gesamtbandbreite enthalten: dieselben Bytes, doppelt ausgewiesen, aber niemals addiert. Wenn ein Premium-Exit die Seite ausgeliefert hat, entspricht dessen Traffic dem gesamten Traffic des Requests, sodass die Seite nicht noch einmal als Standard-Traffic gezählt wird. Deine [Usage & Limits](https://foura.ai/docs/dashboard/quota)-Seite zeigt den Gesamttraffic, den Premium-Anteil daran und das Premium-Kontingent, an dem du gemessen wirst.

Lässt du das Feld weg oder sendest `standard`, verbleibt der Request im Standard-Pool: Nur `premium` erlaubt einen Premium-Exit. Ein erfolgreicher Request, der eine Klasse angibt, erhält `exitClass` in der Response zurück; ein Request ohne dieses Feld erhält dies nicht.

**Aufbrauchen des Kontingents ist kein Fehler.** Ein Request, der `premium` angibt, nachdem das Kontingent verbraucht ist, funktioniert weiterhin: Der Standard-Pool verarbeitet ihn und die Response liefert `standard`. Die einzige Ausnahme ist ein Request, der eine [Exit-Location](#exit-location) angibt: Der Standard-Pool kann diese nicht berücksichtigen, daher wird er abgewiesen.

`exitClass: premium` erfordert einen Tarif, der Premium-Exits enthält. In einem Tarif ohne Premium-Exits verbraucht der Request niemals einen Premium-Exit: Er wird noch vor Beginn der Ausführung mit einem 403-Status und `X-FourA-Limit: plan_limit_premium` abgewiesen (siehe [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits)).


### Exit-Location

Ein Premium-Exit kann von einem Standort innerhalb eines Landes ausgehen und seine Adresse so lange beibehalten, wie du sie benötigst:

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

Die Response nennt den Exit und das Land, aus dem er stammt:

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

Diese `proxy` ID behält alles davon. Übergib sie an Single oder Browser und der Request geht vom selben Ort aus, ohne ein anderes Feld daneben. Siehe [Pinning an Exit](#pinning-an-exit).

Regeln:

- Jeder Wert aus `exitState`, `exitCity`, `exitAsn`, `exitOs` und `exitLifetimeMin` sendet den Request ausschließlich über Premium-Exits. Der Standard-Pool erhält keinen Versuch, da er diese nicht bedienen kann.
- Sie benötigen `exitClass: premium`. Ohne diese Angabe wird der Request mit einem 400-Fehler abgelehnt, der das Feld nennt.
- `exitState`, `exitCity` und `exitAsn` existieren innerhalb eines Landes, daher erfordern sie genau ein Land in `exitCountries`. `exitOs` und `exitLifetimeMin` funktionieren mit mehreren: Der Exit wählt eines davon aus, und `exitCountry` in der Response gibt an, welches.
- `exitState`, `exitCity`, `exitAsn` und `exitOs` erfordern einen Plan mit Geo-Targeting sowie Premium-Exits.
- Wenn kein Premium-Traffic mehr übrig ist, wird der Request mit einem 403-Fehler abgelehnt, der `X-FourA-Limit: plan_limit_premium` enthält, da der Standard-Pool ihn nicht bedienen kann.
- Wenn kein Premium-Exit für diesen Ort antwortet, ist die Response ein Error-Envelope wie unter [exitCountries scoping](#exitcountries-scoping) beschrieben, mit dem Fehler `No premium exit answered for this request` und `code: no_eligible_proxy`. `details.exitCountries` ist vorhanden, wenn du eine Länderliste übergeben hast.

Die Bezeichnungen entsprechen denen, die der [Proxy-Port](https://foura.ai/docs/api/proxy-port) für `state`, `city`, `asn` und `os` akzeptiert.

### Browser-Profil-Rotation

Proxy rotiert Exits. Wenn eine Website den von FourA bereitgestellten Browser ablehnt statt des Exits, von dem er stammt, wechselt Proxy außerdem zu einer anderen Browser-Familie aus dem Katalog. Dadurch entsteht kein zusätzlicher Versuch: Die Rotation ändert, was ein Retry sendet, niemals, ob einer stattfindet.

Proxy merkt sich zudem für eine gewisse Zeit die Familie, die eine Website zuletzt akzeptiert hat, sodass ein späterer Aufruf derselben Website direkt mit dieser Familie statt mit dem Standard starten kann. Die Response nennt sie in `profile`, genau wie bei jeder durch die Rotation gewählten Familie.

Ein explizites `profile`, `browser`, `os` oder `version` auf deinem inneren `request` wird niemals überschrieben. Dasselbe gilt für Requests mit eigenem `User-Agent`- oder `Cookie`-Header, da eine Freigabe an die Signatur gebunden ist, mit der sie erlangt wurde.

---

## Browser Request

`POST /api/browser/`

Öffnet deine URL in einer Chrome-Browser-Instanz. Die Seite lädt, JavaScript wird ausgeführt und du erhältst das vollständig gerenderte HTML samt Cookie-Jar.

### Request Body

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|-----------|------|----------|---------|-------------|
| `url` | string | Ja | - | Ziel-URL |
| `headers` | object | Nein | - | Benutzerdefinierte Header als Key-Value-Paare |
| `cookies` | array | Nein | - | Zu setzende Cookies: `[{name, value, domain?}]` |
| `userAgent` | string | Nein | - | Benutzerdefinierter User-Agent-String |
| `unblocker` | boolean | Nein | `true` | Schließt die Prüfung ab, die eine Seite vor dem Laden anfordert (eine Challenge-Seite oder ein ähnliches Gate). Standardmäßig aktiviert. Setze `false`, um die Antwort der Seite unverändert zu rendern, einschließlich einer Challenge-Seite. |
| `proxy` | string | Nein | - | Proxy-ID aus einer früheren Response, um denselben Exit zu pinnen. Übergib den opaken String unverändert zurück. Eine rohe Proxy-Adresse wird mit `400 Invalid proxy format` abgelehnt. |
| `timeout_ms` | number | Nein | 30000 | Seitenlade-Timeout in ms (max: 120000) |
| `checkStatus` | number | Nein | - | Erwarteter HTTP-Status (Request schlägt bei Abweichung fehl) |
| `checkText` | string | Nein | - | Text, der auf der gerenderten Seite vorkommen muss |
| `lean` | boolean | Nein | `false` | Schließt Bilder, Schriftarten, Medien sowie Requests an bekannte Werbe-, Analyse-, Consent- und Social-Dienste aus. Die Seite selbst, ihre eigenen Skripte und Styles sowie alles, was ein Verifizierungsschritt benötigt, werden weiterhin geladen. Nutze dies, um den Traffic einer Seite zu reduzieren, zum Beispiel über einen gepinnten Premium-Exit. |

### Browser-Uhr an den Exit anpassen

Eine Seite kann die Zeitzone des Browsers auslesen und mit dem Land der erkannten IP abgleichen. Eine Diskrepanz ist eines der einfachsten Signale für Bot-Detektoren und lässt sich ohne Aufwand vermeiden.

Du musst nichts weiter tun. FourA liest das Land aus der `proxy`-ID und der Browser meldet die passende Zeitzone.

- Es ist das **Exit**-Land, also das Land, das das Ziel sieht, nicht der Host-Standort des Proxys. Beide weichen oft genug voneinander ab.
- Wenn FourA das Land des Exits nicht kennt, belässt es die Browser-Uhr unverändert, anstatt zu raten. Ein Premium-Exit hat ein bekanntes Land, wenn du eines mit `exitCountries` bei [Proxy Request](#exit-location) angefordert hast.
- Nur die Uhr folgt dem Land. `Accept-Language` und der ausgelieferte Inhalt der Seite bleiben unberührt, sodass die Seite nicht unerwartet die Sprache wechselt.

### Der Parameter `userAgent`

Sende `userAgent` und genau dieser String wird der Seite, ihren Workern und dem Ziel bereitgestellt. FourA leitet daraus auch die passenden Client Hints ab (`sec-ch-ua`, `sec-ch-ua-platform`, `navigator.platform` und die High-Entropy-Werte, die ein Detektor gezielt anfragt). So gibt der Request nicht einen Browser im Header und einen anderen in JavaScript an.

Der `userAgent` in der Response ist derjenige, der übermittelt wurde. Das ist relevant, wenn du eine Clearance erneut verwendest: Ein `cf_clearance`-Cookie ist an den Exit und den User-Agent gebunden, der ihn erhalten hat. Sende daher den String zurück, den die Response gemeldet hat, nicht den, von dem du annimmst, dass er verwendet wurde. Siehe [Site checks](https://foura.ai/docs/api/site-checks).

Sendest du einen Nicht-Chromium-String (etwa einen Firefox-User-Agent), wird er unverändert übergeben, ohne angehängte Chromium-Brand-Liste.

### Beispiel

```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/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Response:

```json
{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `status` | number | HTTP-Statuscode des Ziels |
| `headers` | object | Response-Header |
| `body` | string or object | Vollständig gerenderter Seiteninhalt. HTML-String, wenn der content-type HTML ist; object, wenn die Seite JSON zurückgegeben hat und dieses automatisch geparst wurde. |
| `cookies` | array | Vollständige Cookie-Objekte der Seite. Jedes Cookie enthält `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite` und weitere Cookie-Eigenschaften. |
| `userAgent` | string | Verwendeter Browser-User-Agent |
| `defenseSolved` | boolean | `true`, wenn bei diesem Aufruf ein Bot-Schutz erkannt und erfolgreich umgangen wurde, andernfalls `false`. Bestimmt, ob der Aufruf 5 oder 10 Credits kostet. |
| `defenses` | object | `present` listet jeden während des Seitenaufrufs erkannten Anbieter auf, `cleared` listet diejenigen auf, deren Freigabe auf der finalen Seite besteht. Ein Anbieter kann in `present` und nie in `cleared` erscheinen. Siehe [Site checks](https://foura.ai/docs/api/site-checks). |
| `proxy` | string | Encodierte ID des Proxys, über den der Request lief (nur wenn beim Request ein `proxy` übergeben wurde). Verwende sie bei Folgeaufrufen wieder, um denselben Exit beizubehalten. |
| `error` | string | Fehlermeldung, falls der Request fehlgeschlagen ist |

---

## Einen Exit anheften

Ein `proxy`-Wert bei einem Single- oder Browser-Request heftet den Exit an, den ein vorheriger Aufruf verwendet hat. Übergib die opaque ID exakt so, wie du sie erhalten hast, niemals eine Proxy-Adresse. Eine ID aus einem Proxy-Request, die ein Land, einen Ort oder eine Lebensdauer festgelegt hat, behält diese bei, sodass der angeheftete Request kein weiteres Feld benötigt.

Drei Werte werden abgelehnt, alle mit dem Code 400:

| Fehler | Bedeutung |
|-------|---------|
| `Invalid proxy format` | Der Wert ist keine von FourA ausgestellte ID. Eine reine Proxy-Adresse führt hierzu. |
| `Proxy not found` | Die ID wurde decodiert, verweist aber nicht mehr auf einen aktiven Exit. Hole dir über einen neuen Aufruf eine frische ID. |
| `Managed exit: this proxy id cannot be pinned to a request` | Der Exit existiert, wird von FourA jedoch nicht für einen spezifischen Request offengehalten. Die ID eines Premium-Exits führt hierzu, wenn dein Tarif kein Premium-Datenvolumen mehr übrig hat. Verwende die Session wieder, mit der sie zurückgegeben wurde, oder führe den Aufruf über `POST /api/proxy/` aus und nutze den Exit, den dieser auswählt. |

Ein angehefteter Premium-Exit wird als Premium-Traffic abgerechnet. Die Response enthält `X-FourA-Exit-Class: premium`, damit du dies pro Request nachvollziehen kannst. Der über den Exit geführte Traffic wird sowohl auf das Premium-Datenvolumen auf deiner Seite [Nutzung & Limits](https://foura.ai/docs/dashboard/quota) als auch auf deine gesamte Bandbreite angerechnet, unabhängig davon, ob die Website die gewünschte Seite zurückgegeben hat. Das Anheften erfordert Premium-Exits in deinem Tarif und verbleibendes Kontingent; andernfalls wird die ID mit dem oben genannten Managed-Exit-400-Fehler abgewiesen.

## HTTP-Statuscodes

| Code | Bedeutung |
|------|-----------|
| 200 | Request abgeschlossen (prüfe das innere `status` auf die Target-Response) |
| 400 | Ungültiger Request-Body, ungültige Parameter, Target-IP in einem privaten/reservierten Bereich, ein Target auf FourAs eigenem API-Host, eine URL mit einem nicht-kodierten Leerzeichen (Single, Proxy, Auto) oder eine Proxy-ID, die nicht gepinnt werden kann. Bei Single, Proxy und Browser wird ein fehlerhaftes Feld benannt: `Invalid request: <field>: <reason>`, bis zu fünf Felder. Nicht abgerechnet. Auto beantwortet denselben Fehler mit HTTP 200 und `status: 400` im Body. |
| 401 | Fehlender oder ungültiger API-Key |
| 403 | Der Endpoint oder ein Parameter ist nicht in deinem Plan enthalten. `X-FourA-Limit` benennt es: `plan_limit_feature` oder `plan_limit_premium`. |
| 404 | `Not Found`: Unter diesem Pfad existiert kein Endpoint. |
| 413 | Der JSON-Request-Body ist größer als 100 KB. Die Antwort ist kein JSON und enthält kein `X-FourA-Request-Id`. |
| 429 | Ein Plan-Limit (`X-FourA-Limit` gesetzt) oder das geteilte Minutenkontingent der Plattform (kein Header) |
| 500 | Interner Serverfehler |
| 502 | `Upstream unavailable`: FourA konnte keine Verbindung zur Engine herstellen. `Malformed JSON from backend`: Die Engine hat geantwortet, aber FourA konnte die Antwort nicht lesen. Erneut versuchen. |
| 503 | Service vorübergehend deaktiviert oder ausgelastet, `API key check temporarily unavailable`, wenn FourA deinen Key kurzzeitig nicht bestätigen konnte (erneut versuchen nach `Retry-After`), oder `Backend service unavailable` während eines Engine-Neustarts. Bei Browser wartet eine Seite bis zu 10 Sekunden auf einen freien Browser, wenn alle belegt sind, und erhält `Backend service unavailable`, falls in dieser Zeit keiner frei wird. |
| 504 | `Upstream timeout`. Die Engine wurde nicht innerhalb des Zeitlimits für diesen Request fertig. Erhöhe `timeout_ms` oder versuche es erneut. |

## Nächste Schritte

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Wann du FourA den Pfad wählen lassen solltest
- [Den richtigen Endpoint wählen](https://foura.ai/docs/guides/choosing-task-type): Wann du Single, Proxy oder Browser manuell wählst
- [Authentifizierung](https://foura.ai/docs/getting-started/authentication): Verwalte deine API-Keys
- [Fehlerbehandlung](https://foura.ai/docs/api/errors): Fehler sauber behandeln
- [Site-Checks](https://foura.ai/docs/api/site-checks): Lies das Feld `defense` aus und wiederhole eine Freigabe
- [Warum ein Proxy-Request keine Versuche mehr hatte](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Lies `attemptReport` aus und reagiere darauf
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Request-Limits verstehen
- [Schnellstart](https://foura.ai/docs/getting-started/quick-start): Dein erster Request in 30 Sekunden
