Request-Ergebnisse
Jeder Request an die FourA-API wird in genau ein Outcome eingestuft, ebenso wie jeder Tunnel über den Proxy-Port. Das Outcome wird einmal am Ende des Aufrufs berechnet und für die Credentials erfasst, die ihn ausgeführt haben. Dein Dashboard, dein Activity Feed und deine Abrechnung greifen alle auf dasselbe Feld zu.
Nur success kostet Credits. Premium-Traffic wird getrennt von Credits gezählt und folgt nicht dem Outcome: siehe Billing Implications.
Die sieben Outcomes
In diesen sieben Zuständen kann ein Request enden. Ein Tunnel verwendet fünf davon: siehe Tunnels Use the Same Vocabulary unten.
| Outcome | Ebene | Bedeutung |
|---|---|---|
success |
n/a | Eine gültige Response wurde übermittelt. Zählt zu deinem abrechenbaren Kontingent. |
application_error |
target | Das Ziel hat HTTP 200 zurückgegeben, aber der Body enthielt ein Fehlerfeld, oder der Body ist eine Bot-Check- oder Blockierungsseite, die FourA erkennt. |
application_fail |
target | Das Ziel hat einen anderen Status als 200 zurückgegeben, den deine validate-Regeln nicht akzeptiert haben oder für den du kein validate gesendet hast, oder gar keine Response, einschließlich eines Ziel-Hostnamens, der nicht aufgelöst werden kann. |
client_error |
caller | Dein Request wurde abgelehnt, bevor er FourA verlassen hat. Ungültige Parameter, fehlerhafter Proxy-Wert, SSRF-geschützte URL. |
rate_limit |
FourA | Der Request wurde vor der Ausführung verweigert: durch eines der Limits deines Tarifs (ein 403 für einen Endpoint oder Parameter, der im Tarif nicht enthalten ist, ein 429 für ein aufgebrauchtes Kontingent) oder durch das geteilte RPM- oder Concurrency-Limit der Plattform. |
service_error |
FourA | Die Engine hat mit einem Serverfehler geantwortet, oder ihr Body war kein gültiges JSON. |
service_fail |
FourA | Das eigene Netzwerk von FourA ist fehlgeschlagen: Die Engine hat nicht rechtzeitig geantwortet, die Verbindung wurde unterbrochen oder du hast die Verbindung getrennt. |
Die Spalte Ebene zeigt dir, wer verantwortlich ist:
- target-Outcomes betreffen die von dir aufgerufene Website. Dein Request hat FourA problemlos erreicht, und FourA hat das Ziel problemlos erreicht. Das Ziel selbst hat einen Fehler zurückgegeben.
- caller-Outcomes bedeuten, dass dein Request keine Chance hatte. Korrigiere die Struktur des Requests.
- FourA-Outcomes liegen bei uns. Wiederhole den Request und prüfe die Statusseite, falls sie weiterhin auftreten.
Wenn eine Zielseite 403 zurückgibt, ist das application_fail, nicht client_error. Dein Aufruf war syntaktisch korrekt. Die Seite hat die Anfrage lediglich abgelehnt.
Wie ein fehlgeschlagener Aufruf aussieht
Ein Aufruf, der FourA erreicht hat und ausgeführt wurde, kommt als HTTP 200 zurück, egal was danach passiert ist. Nur eine Ablehnung vor dem Abruf (400, 401, 403, 413, 429) oder ein Fehler auf Seiten von FourA (5xx) verwendet einen anderen HTTP-Status. Das Outcome wird daher aus dem Body gelesen, nicht aus dem Transport-Status.
| Body | Was passiert ist | Ergebnis |
|---|---|---|
status: 200, headers, data, kein error |
Die Seite wurde ausgeliefert. | success |
status ungleich 200, headers, data, kein error |
Das Ziel hat geantwortet und du hast kein validate gesendet. Seine Antwort steht in data. |
application_fail |
status ungleich 200, headers, data und error |
Das Ziel hat geantwortet und deine validate-Regeln haben es abgelehnt, zum Beispiel Status 404 is not in accept list 200. |
application_fail |
status: 200, headers, data und error |
Das Ziel hat mit HTTP 200 geantwortet und deine validate-Regeln haben es abgelehnt, zum Beispiel Data not in accept list ["product"]. |
application_error |
Nur error und total_time, kein status, kein data |
Das Ziel hat nie mit HTTP geantwortet: Das Redirect-Limit wurde erreicht (Number of redirects hit maximum amount), Timeout bei Verbindung oder Lesezugriff, Verbindung zurückgesetzt oder Antwort war leer. Der Text ist der eigene Grund der Engine. |
application_fail |
status: 0 und error, sonst nichts |
Der Hostname kann nicht aufgelöst werden: could not resolve <host>: <reason>. Keine Engine wurde ausgeführt, und bei Auto gibt es kein meta. Ein erneuter Versuch ändert daran nichts, solange sich das DNS nicht ändert. |
application_fail |
Eine Weiterleitungsschleife aus Sicht der fünften Zeile:
{
"error": "Number of redirects hit maximum amount",
"total_time": 0.808
}
Bei POST /api/proxy/ enthält ein Call, dessen Versuche aufgebraucht sind, error: Download maxTry limit reached und ein attemptReport mit den Zählern (siehe API Errors). Bei POST /api/auto/ enthält eine Leiter, die ausgeführt wurde und fehlschlug, status, error, attempts, ein attemptReport mit den Ursachen und meta.rung auf fail gesetzt.
X-FourA-Credits meldet die geleistete Arbeit, auch bei einem Fehler. Die Abrechnung zählt nur success, daher wird keines der oben genannten fehlerhaften Schemata berechnet.
Erfolg berücksichtigt validate
Ohne validate markiert die API einen Request nur dann als success, wenn das Ziel HTTP 200 zurückgibt.
Mit validate folgt der Erfolg den von dir definierten Regeln. Wenn du der API mitteilst, dass für einen bestimmten Request sowohl 200 als auch 403 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 gilt eine 403-Response als success und wird als ein Request abgerechnet. Eine 500-Response gilt 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 auffordert, JavaScript auszuführen, oder eine Verweigerungsseite, die eine Site mit HTTP 200 ausliefert. 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 Seite.
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, auf Seiten 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 Bandbreitenbegrenzung zählt der Traffic jedes Requests dazu. Ein Request, der durch ein Limit deines eigenen Plans abgelehnt wurde, zählt keinen Traffic.
Tunnel nutzen dasselbe Vokabular
Ein Tunnel über den Proxy-Port endet ebenfalls in einem dieser Ergebnisse, sodass ein Satz von Labels beide Produkte abdeckt. Nur fünf der sieben können auftreten, da die beiden target-Ergebnisse voraussetzen, 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 offene 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 Öffnungsratengrenze. |
service_error |
FourA hatte keinen Exit für deine Anfrage. Normalerweise vorübergehend. |
service_fail |
Das Ziel konnte über keinen von FourA versuchten Exit erreicht werden: DNS, Timeout, Verbindung verweigert. |
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 mit 400 auf der Verbindung selbst beantwortet und erzeugt keine Zeile, sodass sie hier überhaupt nicht auftaucht.
| 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 | Das Datenvolumen 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 Neueröffnungen. 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 sie anrechnen könnte. Der Port zählt stattdessen Bytes. Siehe Wie dein Tarif gemessen wird.
Outcomes im Dashboard ablesen
Jeder Request, den dein API-Key stellt, erscheint im Feed Aktivität mit seinem Outcome-Label. Die Seiten Metriken und Übersicht aggregieren dasselbe Feld für Donut-Diagramme und Zeitverläufe.
Wenn du die Aktivität nach Outcome filterst, kannst du dich auch auf einen einzelnen Endpoint konzentrieren (Auto, Single, Proxy Finder, Browser), um zu sehen, ob eine Fehlerklasse spezifisch für einen von ihnen ist. Stelle das Produkt 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. Manche Fehler sind vorübergehend, die meisten nicht. Wenn X-FourA-Check-Page gesetzt ist, hat die Website eine Check-Seite ausgeliefert: Sende die URL an Auto, das eine Check-Seite als zu bestehenden Schritt behandelt, nicht als Antwort. |
application_fail |
Manchmal | Wenn das Ziel ein Rate Limit anwendet, verlangsame deine Requests. Wenn es dich blockiert, wechsle zum Proxy- oder Browser-Endpoint. |
client_error |
Nein | Der Request wird auf dieselbe Weise erneut 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 | Genauso wie service_error. |
Verwandte Themen
- API Errors: Fehler-Responses auf HTTP-Ebene
- Proxy Port: Die Statuscodes, mit denen die Ablehnung eines Tunnels zurückgegeben wird
- Rate Limits: Was
rate_limitauslöst und in welchen zwei Formaten es zurückkommt - Metrics: Hier siehst du die aufgeschlüsselten Ergebnisse
- Activity Log: Ergebnis-Historie pro Request