reCAPTCHA

Verifying the User's Answer Without Plugins

This page explains how to verify a user's answer for a reCAPTCHA challenge without using a plugin. We offer a variety of plugins for different applications and programming environments, such as PHP and ASP.NET, and we encourage you to look at our multiple plugins before proceeding with the "Do-It-Yourself" (DIY) installation instructions below.

How to Check the User's Answer

After your page is successfully displaying reCAPTCHA, you need to configure your form to check whether the answers entered by the users are correct. This is achieved by doing a POST request to http://www.google.com/recaptcha/api/verify. Below are the relevant parameters.

API Request

URL: http://www.google.com/recaptcha/api/verify

Parameters (sent via POST)  
privatekey (required) Your private key
remoteip (required) The IP address of the user who solved the CAPTCHA.
challenge (required) The value of "recaptcha_challenge_field" sent via the form
response (required) The value of "recaptcha_response_field" sent via the form

API Response

The response from verify is a series of strings separated by \n. To read the string, split the line and read each field. (New lines may be added in the future.)

Line 1 "true" or "false". True if the reCAPTCHA was successful
Line 2 if Line 1 is false, then this string will be an error code. reCAPTCHA can display the error to the user (through the error parameter of www.google.com/recaptcha/api/challenge). Implementations should not depend on error code names, as they may change in the future.

Example: If your response looks like this:
false
incorrect-captcha-sol

... you can add '&error=incorrect-captcha-sol' to the challenge request URL, and the user will get an error code.

Error Code Reference

reCAPTCHA currently returns the following error codes. Note that these codes should not be programmed for specifically as the are subject to change.

invalid-site-private-key We weren't able to verify the private key.
Possible Solutions
  • Did you swap the public and private key? It is important to use the correct one
  • Did you make sure to copy the entire key, with all hyphens and underscores, but without any spaces? The key should be exactly 40 characters long.
The challenge parameter of the verify script was incorrect.
incorrect-captcha-sol The CAPTCHA solution was incorrect.
captcha-timeout The solution was received after the CAPTCHA timed out.
recaptcha-not-reachable reCAPTCHA never returns this error code. A plugin should manually return this code in the unlikely event that it is unable to contact the reCAPTCHA verify server.

Further Reading

  • Customizing Look and Feel
  • Tips and Guidelines
  • Troubleshooting
  • Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.