3. Verify the Response
Before your server processes the form, it sends the response token to CaptchaFox to check that it’s valid. This is what keeps bots out: they can send requests to your server without ever loading the widget.
Make the verification request
Send a POST request with the application/x-www-form-urlencoded content type to:
https://api.captchafox.com/siteverify| Parameter | Required | Description |
|---|---|---|
| secret | Yes | The secret key of your site. |
| response | Yes | The response token from the form field cf-captcha-response. |
| sitekey | No | Your sitekey. Recommended. |
| remoteIp | No | The visitor’s IP address. Must match the IP that solved the challenge. |
Each token can be verified once and is valid for 2 minutes. You can extend this in the portal.
Node.js
Use the @captchafox/node library:
npm install @captchafox/nodeimport { verify } from '@captchafox/node';
const result = await verify(process.env.CAPTCHAFOX_SECRET, req.body['cf-captcha-response'], {
sitekey: 'YOUR_SITEKEY',
remoteIp: req.ip, // optional
});
if (!result.success) {
// Reject the request
}More libraries are listed under Server integrations.
Response
The API responds with a JSON object:
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the token is valid. Always check this field: failed verifications also return status 200. |
| challenge_ts | string | ISO timestamp of the challenge (yyyy-MM-dd'T'HH:mm:ssZZ). Only included on success. |
| hostname | string | Hostname of the site where the challenge was solved. Optional. |
| error-codes | string[] | Why the verification failed. Only included if success is false. See Error codes. |
| insights | object | Verification details. Enterprise plans only. |
{
"success": true,
"challenge_ts": "2026-11-20T10:15:30+00:00",
"hostname": "example.com"
}Error codes
| Error Code | Description |
|---|---|
| missing-input-secret | The secret parameter is missing. |
| invalid-input-secret | The secret parameter is invalid or malformed. |
| missing-input-response | The response parameter is missing. |
| invalid-input-response | The response parameter is invalid or malformed. |
| bad-request | The request is invalid or malformed. |
| timeout-or-duplicate | The token has expired or was already verified. |
| invalid-ip-match | The IP address does not match the remoteIp parameter. |
Common causes of failed verifications
- Verified twice: tokens are single-use. If the user has to resubmit the form, call
captchafox.reset()to get a new token. - Expired: the user waited too long before submitting.
- Keys don’t match: the sitekey and secret key must belong to the same site.
- Wrong IP: behind a proxy,
remoteIpmust be the visitor’s IP. If unsure, leave it out.
Handling outages
Set a timeout of a few seconds on the request. If CaptchaFox can’t be reached (network error, timeout or 5xx status), you can let the request through so your form keeps working, and log it.
Never do this when the API responds with success: false or a 4xx status.
Go-live checklist
- Replace the test keys with your real keys.
- Every protected request is verified on the server and rejected if verification fails.
- The secret key is only stored on your server.
- Your Content Security Policy allows CaptchaFox, if you use one.
- If you use Hidden Mode, the privacy notice is on the page.