← Alle Beiträge
Produktupdate 5 Min. Lesezeit

Validate-Regeln entscheiden jetzt, was als Erfolg gilt

Lege mit Validate-Regeln fest, welche Responses als Erfolg gelten. Akzeptierte Nicht-200-Responses werden jetzt korrekt abgerechnet und in deinem Activity-Feed als Erfolg angezeigt.

apivalidationoutcomesbilling

Die validate-Regeln deines Requests bestimmen jetzt, wie jedes Ergebnis klassifiziert wird. Wenn du einen 403 als akzeptabel deklarierst, gilt ein empfangener 403 als Erfolg, wird als Erfolg abgerechnet und landet neben deinen 200ern in deinem Activity Feed.

Das klingt unbedeutend. Es verändert jedoch grundlegend, wie du Scraping-Genauigkeit im großen Maßstab misst.

Funktionsweise

Jeder Request an FourA erhält eines von sieben Ergebnissen, die über Abrechnung und Analytics entscheiden. Nur success ist abrechenbar. Der Rest teilt sich danach auf, wer den Fehler verursacht hat:

  • application_fail und application_error, wenn die Zielseite die Anfrage abgelehnt oder einen Error-Body zurückgegeben hat
  • client_error, wenn der gesendete Request fehlerhaft war
  • service_fail, service_error und rate_limit, wenn etwas auf unserer Seite den Request blockiert hat

Vor dieser Änderung bedeutete Erfolg genau eines: HTTP 200. Ein 403 war immer application_fail, selbst wenn genau dieser 403 die gewünschte Response war. (Manche Sportdaten-APIs liefern bei geoblockierten Märkten einen 403, und genau auf dieses Signal wartet dein Code.)

Jetzt entscheidet dein validate-Block. Der Request prüft deine Regeln während der Ausführung. Wenn die Response diese erfüllt, lautet das Ergebnis success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/feed",
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 403] },
      "data": { "fail": ["captcha", "Access Denied"] }
    }
  }'

Dies behandelt 200 und 403 als gültige Statuscodes. Enthält der Body einen Verifikationsseiten-Marker oder einen Access-Denied-String, schlägt der Request fehl. Alles andere ist success.

Zwei Regeln, die du dir merken solltest:

  1. Ohne validate bleibt das Verhalten unverändert. Requests, die keine Validierung definieren, werden weiterhin nur bei HTTP 200 abgerechnet. Du entscheidest dich aktiv dafür.
  2. validate funktioniert in beide Richtungen. Accept-Regeln akzeptieren, Fail-Regeln weisen ab. Sie sind kombinierbar. Du kannst also [200, 403] akzeptieren und dennoch abbrechen, wenn der Body den falschen Inhalt enthält.

Auswirkungen

Die Änderung ist vor allem für Teams relevant, deren Zielseiten erwünschte Nicht-200-Responses zurückgeben.

Beispiele aus Requests, die wir täglich sehen:

  • Sportdaten-APIs, die für geogeblockte Märkte ein 403 zurückgeben (weiterhin nützliche Daten, die es wert sind, als Erfolg protokolliert zu werden)
  • E-Commerce-Search-Endpoints, die ein 404 zurückgeben, wenn eine SKU nicht auf Lager ist (ein Signal, das dein Code auswertet, kein Fehler)
  • Streaming- und Partial-Content-APIs, die 206 zurückgeben

Vor der Änderung mussten diese Teams ihre eigene Buchführung über unseren Activity-Logs betreiben. Sie konnten der Spalte outcome nicht vertrauen, weil ihre Definition von Erfolg nicht mit unserer übereinstimmte. Sie wurden nach einer Zahl abgerechnet, die für sie gar nicht relevant war.

Jetzt spiegelt die Spalte die Realität wider. Der Activity-Tab in deinem Dashboard zeigt genau das an, was du als Erfolg definiert hast, nicht das, was wir vermutet haben. Deine abgerechneten Summen stimmen mit deinen eigenen Zählungen überein (frühe Ergebnisse: Die Änderung gilt nur für neue Einträge, ältere Activity-Zeilen behalten ihre ursprüngliche Klassifizierung).

Der praktische Effekt für einen Scraping-Job: weniger Abgleichschritte zwischen deiner Pipeline und unserer Rechnung. Wenn du den Response-Body ohnehin schon nachträglich validiert hast, kannst du diesen Vertrag direkt in den Request verlagern und musst keine parallelen Pass/Fail-Regeln mehr außerhalb unserer API pflegen. Eine einzige Definition darüber, ob ein Request seinen Platz in deinem Datensatz verdient hat, statt zweier, die sich widersprechen.

Aber wir haben das Sicherheitsnetz beibehalten. Wenn du keinen validate-Block übergibst, ändert sich nichts. Der Classifier fällt auf "200 bedeutet Erfolg" zurück, sodass Requests, die gestern funktioniert haben, heute genauso funktionieren.

Für Power-User

validate akzeptiert drei Regelsätze, die unabhängig voneinander laufen: status, headers und data. Jeder nimmt optionale accept- und fail-Listen an.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/9876",
    "followRedirects": 5,
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 304] },
      "headers": { "accept": { "content-type": "application/json" } },
      "data": { "accept": ["\"price\":"], "fail": ["maintenance", "captcha"] }
    }
  }'

Das erfordert:

  • Status ist 200 oder 304
  • Response deklariert einen JSON-Content-Type
  • Body enthält ein price-Feld
  • Body enthält keinen Wartungshinweis oder keine Verifizierungsseite

Schlägt eine Regel fehl, lautet das Ergebnis application_fail. Passt alles, ist es success. Der Classifier läuft direkt im Request, du sparst dir also den Roundtrip eines separaten Validierungsschritts.

Kombiniert mit followRedirects: Folge bis zu fünf Hops und validiere dann die finale Response. Ein Bait-and-Switch von einer sauberen URL zu einer Verifizierungsseite schlägt sauber fehl, anstatt dein Dataset zu verunreinigen.

Und ein Tipp aus unseren eigenen Scrapern: Deklariere data.fail-Muster offensiv. Ein 200 OK mit einer Verifizierungsseite im Body ist die häufigste Ursache für unbemerktes Scheitern auf geschützten Websites. Behandle den Body als maßgeblich, nicht den Statuscode.

Das vollständige Schema findest du in der Request-Referenz mit jedem validate-Feld und dessen Zusammenspiel.

Was kommt als Nächstes

Wir arbeiten an mächtigeren Regel-Primitiven: Regex-Matcher für data, strukturierte JSON-Path-Prädikate und flexibleres Header-Matching. Das Prinzip bleibt gleich: Du definierst, wie Erfolg aussieht; die API setzt es durchgängig um, vom Request bis zu deiner Rechnung.

Wenn dein Scraper ausfällt, sollte er sich lautstark melden. Und wenn er anhand von dir definierter Regeln läuft, kannst du diesen Zahlen wirklich vertrauen.