Troubleshooting

Important: Version 1.0 of the reCAPTCHA API is no longer supported, please upgrade to Version 2.0. Learn more

I Can't Work Out Where to Add reCAPTCHA

This advice applies to everyone who's integrating reCAPTCHA -- irrespective of language.

Firstly you need to identify two hot spots in your code. These are the places where you'll be adding the reCAPTCHA calls.

  • Display reCAPTCHA: The first hot spot is the code that generates the form. Hopefully that's easy enough to find (by looking for a <form> tag in your html) and you have been able to display the CAPTCHA on your form.

  • Check reCAPTCHA: The second hot spot is the one that seems to cause people problems. You need to identify the code that handles form submission -- that is the code that runs when the user clicks on submit. It's hard to generalize about what this code looks like but here are some clues that may help you:

    • if your form can ever display an error message, for example if a required field is blank, look for the code that generates that error message.
    • if your form places information in a database look for code that does a SQL INSERT.
    • if your form sends mail, search for the code that does that.

    Form Already Has Validation

    Life will be easier if your form already has some validation logic (i.e. it handles invalid input from the user by displaying a message instead of performing whatever action it normally would). If that's the case and you can find the code that does that you're nearly home free. If the form can display an error message search for the text of the error message within the code and you're sure to be close. Once you've found the validation code you need to add a call to the check_answer function in addition to whatever other checks are there (email address blank? age too young? etc.).

    Form Has No Validation

    If there's currently no validation logic for your form -- if clicking on submit always succeeds -- then you have a more tricky problem. In that case you'll have to add the reCAPTCHA validation code right before the existing form handling code does whatever it does when the user submits. You'll also have to figure out how to redisplay the form to give the user another attempt at the captcha. Unfortunately there's no one stock answer to how you do that. It depends entirely on the structure of the code you already have. If the existing code isn't too complex you may have luck posting it on the reCAPTCHA developer forum and asking for advice. (If you do post there, be sure to include enough information for others to help you; simply saying "my code doesn't work" usually doesn't yield good results.)

    • It's Not Working! Help!

    Before doing anything else make sure you're using the correct keys. Are your public and private keys swapped? Did you remember to put the private key in the form handler as well as putting the public key in the form?

    Note that Mailhide uses different keys from the main form-based reCAPTCHA.

    Be sure that your form uses the POST method, or else change the reCAPTCHA form handler variables to GET instead of POST.

    If reCAPTCHA was working and you suddenly start getting "An internal error occurred", did you recently delete the Google account that you used to sign up for the keys? If so, register for new keys with an active account and try those.

    reCAPTCHA is Accepting Incorrect Words

    Humans make errors and we understand that. In reCAPTCHA we use an advanced risk analysis engine to determine whether the incoming request is from a human or not. When we are highly confident that users are human, we allow them to make small mistakes.

    No, I Mean *Totally* Incorrect Words

    If reCAPTCHA is accepting any input whatsoever, you probably aren't correctly validating the reCAPTCHA answer with the API servers. That is, either: (1) you are not correctly calling https://www.google.com/recaptcha/api/verify (or the equivalent function if you're using a plugin, such as recaptcha_check_answer in PHP), or (2) you are not taking the appropriate action given the response from our servers. Please see the specific instructions that you used to install reCAPTCHA (whether it be through a plugin or not) to learn how to check whether the user entered the answer correctly.

    My Users Are Starting To Get One Word Captchas

    reCAPTCHA is not always about two words. It is a test to tell human and robots apart. In cases where we have high confidence that you are human, we will serve you a much easier captcha (sample below). Our system relies on your entire engagement with reCAPTCHA -- before, during, and after solving it -- to decide if you pass or fail the test, rather than on the solution alone.

    Easy captcha

    If you are curious about the security of these easy captchas, please refer to our blog: http://googleonlinesecurity.blogspot.com/2013/10/recaptcha-just-got-easier-but-only-if.html