← 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. Deklariere einen 403 als akzeptabel, und ein gelieferter 403 gilt als Erfolg, wird als Erfolg abgerechnet und landet neben deinen 200ern in deinem Activity-Feed.

Das klingt unbedeutend. Es ändert aber, wie du die Scraping-Genauigkeit im großen Stil misst.

So funktioniert es

Jeder Request an FourA erhält eines von sieben Ergebnissen, die über Abrechnung und Analytics entscheiden. Nur success wird abgerechnet. 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 von dir 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 eine Sache: HTTP 200. Ein 403 war immer application_fail, selbst wenn du wusstest, dass dieser 403 die gewünschte Response war. (Einige Sportdaten-APIs geben für geogeblockte Märkte einen 403 zurück, und genau auf dieses Signal wartet dein Code.)

Jetzt entscheidet dein validate-Block. Der Request führt deine Regeln während der Ausführung aus. Wenn die Response sie erfüllt, ist das Ergebnis success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer 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 as valide Statuscodes. Wenn der Body einen CAPTCHA-Marker oder einen Access-Denied-String enthält, 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 ohne Validierungsdeklaration werden weiterhin nur bei HTTP 200 abgerechnet. Du entscheidest dich aktiv dafür.
  2. validate funktioniert in beide Richtungen. Accept-Regeln lassen Requests durch, Fail-Regeln lehnen sie ab. Sie lassen sich kombinieren. Du kannst also [200, 403] akzeptieren und den Request trotzdem fehlschlagen lassen, wenn der Body den falschen Inhalt enthält.

Auswirkungen

Die Änderung ist besonders wichtig für Teams, deren Zielseiten Nicht-200-Responses zurückgeben, die sie eigentlich haben wollen.

Beispiele aus Requests, die wir täglich sehen:

  • Sportdaten-APIs, die für geogeblockte Märkte einen 403 zurückgeben (immer noch nützliche Daten, immer noch wertvoll, um als Erfolg protokolliert zu werden)
  • E-Commerce-Such-Endpoints, die einen 404 zurückgeben, wenn eine SKU ausverkauft ist (ein Signal, das dein Code liest, kein Fehler)
  • Streaming- und Partial-Content-APIs, die 206 zurückgeben

Vor der Änderung führten diese Teams ihre eigene Buchhaltung zusätzlich zu unseren Activity-Logs. Sie konnten der Spalte outcome nicht vertrauen, weil ihre Definition von Erfolg nicht mit unserer übereinstimmte. Sie wurden auf Basis einer Zahl abgerechnet, die sie eigentlich gar nicht interessierte.

Jetzt spiegelt die Spalte die Realität wider. Der Activity-Tab in deinem Dashboard zeigt das an, was du als Erfolg definiert hast, nicht das, was wir vermutet haben. Deine Abrechnungssummen entsprechen dem, was du selbst zählen würdest (erste Ergebnisse: Die Änderung gilt nur für die Zukunft, ältere Activity-Zeilen behalten also ihre ursprüngliche Klassifizierung).

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

But wir haben das Sicherheitsnetz behalten. Wenn du keinen validate-Block übergibst, ändert sich nichts. Der Klassifizierer fällt auf „200 bedeutet Erfolg“ zurück, sodass Requests, die gestern funktionierten, heute genauso funktionieren.

Für Power-User

validate akzeptiert drei Regelsätze, die unabhängig voneinander ausgeführt werden: status, headers und data. Jeder davon nimmt optionale accept- und fail-Listen entgegen.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer 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"] }
    }
  }'

Dies erfordert:

  • Status ist 200 oder 304
  • Response gibt einen JSON-Content-Type an
  • Body enthält ein Preisfeld
  • Body enthält keinen Wartungshinweis und keine CAPTCHA-Falle

Wenn eine Regel fehlschlägt, ist das Ergebnis application_fail. Wenn alles durchgeht, ist es success. Der Klassifizierer läuft direkt im Request selbst, sodass du dir den Roundtrip sparst, den ein separater Validierungsschritt kosten würde.

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 CAPTCHA-Sperre schlägt sauber fehl, anstatt deinen Datensatz zu verunreinigen.

Und ein Tipp aus dem Betrieb unserer eigenen Scraper: Deklariere data.fail-Muster aggressiv. Ein 200 OK mit einem CAPTCHA darin ist der häufigste stille Fehler auf geschützten Seiten. Behandle den Body als maßgeblich, nicht den Statuscode.

Das vollständige Schema findest du in der Request-Referenz, die jedes validate-Feld und dessen Kombinationen auflistet.

Was als Nächstes kommt

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 deklarierst, wie Erfolg aussieht; die API respektiert es End-to-End, vom Request bis zu deiner Rechnung.

Wenn dein Scraper ausfällt, sollte er lautstark fehlschlagen. Und wenn er nach Regeln funktioniert, die du selbst geschrieben hast, ist das eine Zahl, der du tatsächlich vertrauen kannst.