Skip to Content
Erste Schritte3. Antwort verifizieren

3. Antwort verifizieren

Bevor Ihr Server das Formular verarbeitet, sendet er das Antwort-Token an CaptchaFox und prüft, ob es gültig ist. So halten Sie Bots fern: Sie können Anfragen an Ihren Server senden, ohne das Widget je zu laden.

Verifizierungsanfrage senden

Senden Sie eine POST-Anfrage mit dem Content-Type application/x-www-form-urlencoded an:

https://api.captchafox.com/siteverify
ParameterErforderlichBeschreibung
secretJaDer Geheimschlüssel Ihrer Seite.
responseJaDas Antwort-Token aus dem Formularfeld cf-captcha-response.
sitekeyNeinIhr Seitenschlüssel. Empfohlen.
remoteIpNeinDie IP-Adresse des Besuchers. Muss mit der IP übereinstimmen, die die Herausforderung gelöst hat.

Jedes Token kann einmal verifiziert werden und ist 2 Minuten gültig. Sie können diese Dauer im Portal verlängern.

Verwenden Sie die Bibliothek @captchafox/node :

npm install @captchafox/node
import { verify } from '@captchafox/node'; const result = await verify(process.env.CAPTCHAFOX_SECRET, req.body['cf-captcha-response'], { sitekey: 'IHR_SITEKEY', remoteIp: req.ip, // optional }); if (!result.success) { // Anfrage ablehnen }

Weitere Bibliotheken finden Sie unter Server-Integrationen.

Antwort

Die API antwortet mit einem JSON-Objekt:

FeldTypBeschreibung
successbooleanOb das Token gültig ist. Prüfen Sie immer dieses Feld: Auch fehlgeschlagene Verifizierungen liefern den Status 200.
challenge_tsstringISO-Zeitstempel der Herausforderung (yyyy-MM-dd'T'HH:mm:ssZZ). Nur bei Erfolg enthalten.
hostnamestringHostname der Seite, auf der die Herausforderung gelöst wurde. Optional.
error-codesstring[]Warum die Verifizierung fehlgeschlagen ist. Nur enthalten, wenn success false ist. Siehe Fehlercodes.
insightsobjectDetails über die Verifizierung. Nur in Enterprise-Plänen.
{ "success": true, "challenge_ts": "2026-11-20T10:15:30+00:00", "hostname": "example.com" }

Fehlercodes

FehlercodeBeschreibung
missing-input-secretDer Geheimschlüssel fehlt.
invalid-input-secretDer Geheimschlüssel ist ungültig oder falsch formatiert.
missing-input-responseDas Antwort-Token fehlt.
invalid-input-responseDas Antwort-Token ist ungültig oder fehlerhaft.
bad-requestDie Anfrage ist ungültig oder fehlerhaft formuliert.
timeout-or-duplicateDas Token ist abgelaufen oder wurde bereits verifiziert.
invalid-ip-matchDie IP-Adresse stimmt nicht mit dem Parameter remoteIp überein.

Häufige Ursachen für fehlgeschlagene Verifizierungen

  • Doppelt verifiziert: Tokens können nur einmal verwendet werden. Muss der Nutzer das Formular erneut absenden, rufen Sie captchafox.reset() auf, um ein neues Token zu erhalten.
  • Abgelaufen: Der Nutzer hat zu lange mit dem Absenden gewartet.
  • Schlüssel passen nicht zusammen: Seitenschlüssel und Geheimschlüssel müssen zur selben Seite gehören.
  • Falsche IP: Hinter einem Proxy muss remoteIp die IP des Besuchers sein. Im Zweifel lassen Sie den Parameter weg.

Umgang mit Ausfällen

Setzen Sie ein Timeout von wenigen Sekunden für die Anfrage. Ist CaptchaFox nicht erreichbar (Netzwerkfehler, Timeout oder 5xx-Status), können Sie die Anfrage durchlassen, damit Ihr Formular nutzbar bleibt, und den Fall protokollieren. Tun Sie das niemals, wenn die API mit success: false oder einem 4xx-Status antwortet.

Checkliste vor Livegang

  • Die Testschlüssel sind durch Ihre echten Schlüssel ersetzt.
  • Jede geschützte Anfrage wird auf dem Server verifiziert und abgelehnt, wenn die Verifizierung fehlschlägt.
  • Der Geheimschlüssel ist nur auf Ihrem Server gespeichert.
  • Ihre Content Security Policy erlaubt CaptchaFox, falls Sie eine verwenden.
  • Wenn Sie den versteckten Modus verwenden, ist der Datenschutzhinweis auf der Seite.
Zuletzt aktualisiert am