Request-Ergebnisse

Jeder Request an die FourA API wird genau einem Outcome zugeordnet, ebenso jeder Tunnel über den Proxy-Port. Das Outcome wird einmalig am Ende des Aufrufs berechnet und dem zugehörigen Credential zugewiesen. Dein Dashboard, dein Aktivitäts-Feed und die Abrechnung nutzen dasselbe Feld.

Nur success kostet Credits. Premium-Traffic wird getrennt von Credits gezählt und hängt nicht vom Outcome ab: siehe Billing Implications.

Die sieben Outcomes

Dies sind die sieben möglichen Outcomes eines Requests. Ein Tunnel nutzt fünf davon: siehe Tunnels Use the Same Vocabulary unten.

Outcome	Layer	Bedeutung
`success`	k. A.	Eine gültige Response wurde geliefert. Zählt gegen dein abrechenbares Kontingent.
`application_error`	target	Das Ziel gab HTTP 200 zurück, aber der Body enthielt ein Fehlerfeld oder ist eine von FourA erkannte Bot-Check-Seite.
`application_fail`	target	Das Ziel gab einen Non-2xx-Status zurück, den deine `validate`-Regeln nicht akzeptiert haben, oder gar keine Response (inklusive nicht auflösbarer Hostnamen).
`client_error`	caller	Dein Request wurde abgelehnt, bevor er FourA verlassen hat. Ungültige Parameter, fehlerhafter Proxy-Wert, durch SSRF-Schutz blockierte URL.
`rate_limit`	FourA	Der Request wurde vor der Ausführung verweigert: durch ein Limit deines Tarifs (403 für einen nicht enthaltenen Endpoint oder Parameter, 429 bei aufgebrauchtem Kontingent) oder durch die geteilten RPM- oder Concurrency-Limits der Plattform.
`service_error`	FourA	Die Engine antwortete mit einem Serverfehler oder der Body war kein gültiges JSON.
`service_fail`	FourA	Das Netzwerk von FourA ist fehlgeschlagen: Die Engine antwortete nicht rechtzeitig, die Verbindung brach ab oder du hast die Verbindung getrennt.

Die Spalte Layer zeigt, wer verantwortlich ist:

target-Outcomes betreffen die aufgerufene Website. Dein Request erreichte FourA und FourA erreichte das Ziel. Das Ziel selbst hat einen Fehler zurückgegeben.
caller-Outcomes bedeuten, dass dein Request keine Chance hatte. Korrigiere das Format des Requests.
FourA-Outcomes liegen bei uns. Wiederhole den Request und prüfe die Statusseite, falls sie anhalten.

Gibt eine Zielseite 403 zurück, ist das application_fail, nicht client_error. Dein Aufruf war korrekt aufgebaut. Die Seite hat ihn schlicht abgelehnt.

Erfolg ist `validate`-abhängig

Ohne validate markiert die API einen Request nur dann als success, wenn das Ziel HTTP 200 zurückgibt.

Mit validate richtet sich der Erfolg nach deinen definierten Regeln. Wenn du der API mitteilst, dass 200 und 403 für einen bestimmten Request akzeptabel sind, wird ein 403 als success zurückgegeben. Der Body erreicht dich weiterhin unverändert.

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://target.example/feed",
    "validate": {
      "status": { "accept": [200, 403] }
    }
  }'

In diesem Aufruf zählt eine 403-Response als success und wird als ein Request abgerechnet. Eine 500-Response zählt als application_fail und wird nicht abgerechnet.

Dieselbe Logik gilt für validate.headers und validate.data. Jede Response, die die Engine anhand deiner Regeln akzeptiert, wird unabhängig vom HTTP-Status als success zurückgegeben.

Eine Antwort ist niemals success, mit oder ohne validate: ein HTTP 200, dessen Body eine von FourA erkannte Bot-Check-Seite ist, wie eine visuelle Verifizierungsaufgabe oder eine Seite, die den Browser nur zur Ausführung von JavaScript auffordert. Dieser Request ist application_error und wird nicht abgerechnet. Der Body erreicht dich weiterhin unverändert, und der Header X-FourA-Check-Page benennt die Prüfseite.

Auswirkungen auf die Abrechnung

Ergebnis	Abrechenbar	Zählt zum Kontingent
`success`	Ja	Ja
`application_error`	Nein	Nein
`application_fail`	Nein	Nein
`client_error`	Nein	Nein
`rate_limit`	Nein	Nein
`service_error`	Nein	Nein
`service_fail`	Nein	Nein

Nur Requests, die die von dir angeforderten Daten geliefert haben, werden abgerechnet. Fehler auf Seiten von FourA, des Ziels oder auf deiner eigenen Seite sind alle kostenlos.

Die Tabelle bezieht sich auf Credits. Premium-Traffic wird getrennt davon gezählt: Ein Request, der einen Premium-Exit versucht hat, zählt den Traffic, den dieser Versuch übertragen hat, unabhängig vom Ergebnis, da der Exit in jedem Fall genutzt wurde. Ein Versuch, der noch lief, als ein anderer Exit geantwortet hat, wird sofort gestoppt, und der bis dahin übertragene Traffic zählt ebenfalls.

Standard-Traffic richtet sich ebenfalls nicht nach dem Ergebnis: Bei einem Plan mit Bandbreitenlimit zählt der Traffic jedes Requests dazu. Ein Request, der durch ein Limit deines eigenen Plans abgelehnt wird, zählt keinen Traffic.

Tunnel nutzen dasselbe Vokabular

Ein Tunnel über den Proxy-Port endet ebenfalls in einem dieser Ergebnisse, sodass ein Satz an Labels beide Produkte abdeckt. Nur fünf der sieben können auftreten, da die beiden target-Ergebnisse erfordern, dass FourA die Antwort des Ziels gesehen hat, und die Antwort eines Tunnels dein eigener verschlüsselter Traffic ist.

Ergebnis	Bei einem Tunnel bedeutet dies
`success`	Der Tunnel wurde geöffnet und dein Tool hat ihn erhalten.
`client_error`	FourA öffnet diesen Tunnel nicht: eine private oder reservierte Adresse oder ein Port, der nicht bedient wird.
`rate_limit`	Einer der Werte deines Plans wurde erreicht (gleichzeitig geöffnete Tunnel, Tunnelöffnungen pro Minute, der Standard-Traffic für den Zeitraum, Premium-Traffic, den du nicht hast), oder der Port selbst war an seiner Kapazitäts- oder Öffnungsrate.
`service_error`	FourA hatte keinen Exit für deine Anfrage. Meist vorübergehend.
`service_fail`	Das Ziel konnte über keinen von FourA versuchten Exit erreicht werden: DNS, Timeout, Verbindung abgelehnt.
`application_error`	Tritt bei einem Tunnel nie auf.
`application_fail`	Tritt bei einem Tunnel nie auf.

Eine Ablehnung enthält auch einen kurzen Grund, und das Dashboard zeigt ihn in deinen eigenen Begriffen statt in unseren an. Eine Option, die FourA nicht erfüllen kann, wird direkt auf der Verbindung mit 400 beantwortet und schreibt keine Zeile, sodass sie hier überhaupt nicht erscheint.

Grund auf dem Bildschirm	Was aufgebraucht war
port not in plan	Dein Tarif enthält den Proxy-Port nicht
tunnels at once	Alle Tunnel, die dein Tarif gleichzeitig erlaubt, waren in Nutzung
openings per minute	Die Tunnelöffnungen deines Tarifs für diese Minute waren aufgebraucht
traffic used up	Der Traffic deines Tarifs für diesen Zeitraum ist aufgebraucht
premium not available	Premium-Traffic ist in deinem Tarif derzeit nicht verfügbar
port was full	Der Port selbst war voll ausgelastet oder erreichte das Limit für Öffnungsraten. Versuche es gleich noch einmal.
port not served	FourA öffnet keine Tunnel zu diesem Port
private address	Private und reservierte Adressen können nicht erreicht werden

Nichts an einem Tunnel wird in Credits abgerechnet, da ein Tunnel keinen Request hat, dem man einen berechnen könnte. Der Port zählt stattdessen Bytes. Siehe Wie dein Tarif gemessen wird.

Outcomes im Dashboard ablesen

Jeder Request, den dein API-Key ausführt, erscheint im Activity-Feed mit seinem Outcome-Label. Die Seiten Metrics und Overview aggregieren dasselbe Feld für Donut-Diagramme und Zeitachsen.

Wenn du Activity nach Outcome filterst, kannst du dich auch auf einen einzelnen Endpoint (Auto, Single, Proxy Finder, Browser) konzentrieren, um zu sehen, ob eine Fehlerklasse spezifisch für einen davon ist. Stelle Product auf der Seite auf Proxy um, und dieselben Outcome-Pills filtern deine Tunnel.

Retry-Heuristiken

Eine grundlegende Retry-Policy basierend auf Outcomes:

Outcome	Retry sicher?	Wann
`success`	n/a	Du hast die Response.
`application_error`	Manchmal	Lies den Error-Body des Ziels. Einige sind vorübergehend, die meisten nicht. Wenn `X-FourA-Check-Page` gesetzt ist, hat die Website eine Prüfseite ausgeliefert: Sende die URL an Auto, das eine Prüfseite als Zwischenschritt behandelt, nicht als Antwort.
`application_fail`	Manchmal	Wenn das Ziel dich mit Rate Limits belegt, verlangsame die Frequenz. Wenn es dich blockiert, wechsle zum Proxy- oder Browser-Endpoint.
`client_error`	Nein	Der Request wird auf dieselbe Weise wieder fehlschlagen. Korrigiere die Eingabe.
`rate_limit`	Kommt darauf an	Halte die Wartezeit ein, die dir die Response vorgibt: `Retry-After`, `retry_after_seconds` oder `retryAfter`. Bei `plan_limit_browser_daily` pausiere bis Mitternacht UTC; bei `plan_limit_credits` oder `plan_limit_bandwidth` pausiere bis `resets_at`; bei `plan_limit_feature` oder `plan_limit_premium` passe den Request an.
`service_error`	Ja	Kurzer exponentieller Backoff.
`service_fail`	Ja	Genau wie `service_error`.