Best practices

Client-side

Handle script load failure

The widget api.js may fail to load for various reasons (bad internet connectivity, extensions blocking 3rd party scripts, improper CSP setup, …).

You should handle such load errors using the error javascript event.

Handle browsers with scripting disabled

Users can disable Javascript in their browser settings which is required for CAPTCHAs to function properly.

You should include a <noscript> element in your form that instructs users to enable Javascript.

Example:

<form method="POST">
  <div class="p-captcha" data-sitekey="..."></div>
  <noscript style="color:red">Javascript is required for this form.</noscript>
</form>

Disable form submission until the CAPTCHA is solved

You use the formSubmitDisable option (data-form-submit-disable) to prevent form submission until the CAPTCHA is solved.

Server-side

Validate solution before calling the /siteverify API

Using Offline Validation you can validate a solution is formatted correctly before calling the siteverify API, allowing you to filter out malicious spam requests without making an expensive API call.

Pass the remoteip parameter

The siteverify API accepts an optional parameter called remoteip.

We recommend passing the IP address of the user who submitted the solution to your server, so we can validate that the CAPTCHA was solved by that individual, and not a CAPTCHA farm or otherwise offloaded to a third party.

Ratelimit

If your endpoint is important enough to require a CAPTCHA, it should probably be protected by regular ratelimits as well.

Retry requests on failure

The siteverify API might return unexpected errors sometimes. You should handle them correctly.