Installation
Error Codes
Errors come from two places: the widget (calling generate-token in the browser) and your server (calling verify-token). The exact message strings are below — they appear in the JSON body and in your browser/network logs.
Widget errors (generate-token)
| Error | HTTP | Meaning / fix |
|---|---|---|
| Invalid site key | 400 | Site key doesn't exist, has a typo, or the site was deactivated in the dashboard. Copy the key again from the site card and make sure the site is active. |
| Too many requests. Please try again later. | 429 | Per-IP limit hit (30 requests/minute). The widget retries on its own; if you see it constantly, check for loops re-rendering the widget or other tabs sharing the IP. |
| Too many requests for this site key. | 429 | Per-site limit hit (60 requests/minute across all visitors). Normal traffic won't trigger this — look for a bot hammering the page. |
| Server error | 500 | The aiCaptcha instance failed. Retry after a moment; if it persists, check the instance logs (self-hosters: see Self-hosting). |
When the widget shows "Verification failed"
The badge displays its failure state when
generate-token errors, the network call fails, or the visitor was scored as a bot (verified: false). The visitor can retry by re-submitting the form — the widget clears its failed state on submit.Server errors (verify-token)
Returned as JSON with HTTP 200 unless the request itself is malformed: { "success": false, "error": "..." }
| Error | HTTP | Meaning / fix |
|---|---|---|
| Missing parameters | 400 | secret or response was empty. Make sure you forward both from the submission. |
| Invalid secret key | 400 | Wrong secret, or the site is deactivated. Use the secret key of the same site whose site key the widget used. |
| Invalid token | 200 | Token unknown, expired (they live 2 minutes), or issued for a different site. Verify promptly after the form arrives; check that you're not mixing keys from two sites. |
| success: false + score | 200 | Not an error — the token is valid but the visitor was scored below the 0.7 threshold (likely a bot). Reject or challenge the submission. |
Debugging a failed integration
The fastest way to see what the API actually said is to call verify-token directly with the token from your form:
bash
curl "https://your-instance.com/api/verify-token?secret=YOUR_SECRET&response=PASTE_TOKEN"- Nothing renders at all — check the browser console: the script URL is probably wrong, or the page is HTTP while the instance is HTTPS.
- "Invalid site key" on a working page — the site was deactivated or deleted; reactivate it in Sites.
- Works locally, fails in production — the keys belong to a different site record; register the production domain as its own site.
Still stuck? See FAQ & Troubleshooting or the API Reference for the full request/response shapes.