Request-Ergebnisse

Jeder Request an die FourA-API wird genau einem Ergebnis zugeordnet. Das Ergebnis wird einmalig zum Zeitpunkt des Requests berechnet und für deinen API-Key erfasst. Dein Dashboard, dein Activity-Feed und deine Abrechnung lesen alle dasselbe Feld aus.

Nur success ist abrechenbar.

Die sieben Ergebnisse

Ergebnis	Ebene	Bedeutung
`success`	n/a	Eine gültige Response wurde zugestellt. Zählt für dein abrechenbares Kontingent.
`application_error`	target	Das Ziel gab HTTP 200 zurück, aber der Body enthielt ein Fehlerfeld.
`application_fail`	target	Das Ziel gab einen Nicht-2xx-Status zurück, den deine `validate`-Regeln nicht akzeptiert haben, oder gar keine Response.
`client_error`	caller	Dein Request wurde abgelehnt, bevor er FourA verlassen hat. Ungültige Parameter, fehlerhafter Proxy-Wert, durch SSRF geschützte URL.
`rate_limit`	FourA	Dein RPM- oder Concurrency-Limit wurde erreicht.
`service_error`	FourA	Das Backend gab einen 5xx-Status zurück oder sein Body war kein gültiges JSON.
`service_fail`	FourA	Netzwerkfehler: Timeout, Verbindungsaufbau verweigert, DNS-Fehler, Client-Verbindungsabbruch.

Die Spalte „Ebene“ zeigt, wer verantwortlich ist:

target-Ergebnisse betreffen die von dir aufgerufene Seite. Dein Request hat FourA erfolgreich erreicht, und FourA hat das Ziel erfolgreich erreicht. Das Ziel selbst hat einen Fehler zurückgegeben.
caller-Ergebnisse bedeuten, dass dein Request keine Chance hatte. Korrigiere das Request-Format.
FourA-Ergebnisse liegen in unserer Verantwortung. Versuche es erneut und prüfe die Statusseite, falls sie weiterhin auftreten.

Wenn eine Zielseite 403 zurückgibt, ist das ein application_fail, kein client_error. Dein Aufruf war korrekt formatiert. Die Seite hat den Zugriff lediglich verweigert.

Success 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 200 und 403 für einen bestimmten Request akzeptabel sind, wird ein 403 als success zurückgegeben. Der Body erreicht dich dennoch 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] }
    }
  }'

Bei 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 berechnet.

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

Auswirkungen auf die Abrechnung

Ergebnis	Abrechenbar	Zählt für 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 berechnet. Fehler aufseiten von FourA, des Ziels oder auf deiner Seite sind kostenlos.

Ergebnisse im Dashboard ablesen

Jeder Request, den dein API-Key ausführt, wird im Activity-Feed mit seinem Ergebnis-Label angezeigt. Die Seiten Metrics und Overview aggregieren dasselbe Feld für Kreisdiagramme und Zeitachsen.

Wenn du die Activity nach Ergebnis filterst, kannst du dich auch auf ein einzelnes Produkt (Single, Proxy, Browser) konzentrieren, um zu sehen, ob eine bestimmte Fehlerklasse spezifisch für einen Endpoint ist.

Retry-Heuristiken

Eine erste Retry-Richtlinie basierend auf den Ergebnissen:

Ergebnis	Retry sicher?	Wann
`success`	n/a	Du hast die Response.
`application_error`	Manchmal	Lies den Fehler-Body des Ziels. Einige sind vorübergehend, die meisten nicht.
`application_fail`	Manchmal	Wenn das Ziel deine Rate limitiert, verlangsame die 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`	Ja	Beachte `retryAfter` aus dem Response-Body.
`service_error`	Ja	Kurzer exponentieller Backoff.
`service_fail`	Ja	Genauso wie `service_error`.