Creating a WP_Error

I’m working on a new WordPress plugin at the moment, one to take advantage of the hCaptcha service.  hCaptcha is a drop-in replacement for Google’s reCaptcha, so it keeps bots (and other non-humans) from posting forms on your website.

There are a few benefits to using hCaptcha over reCaptcha though…

  1. Privacy focused – unlike everything that Google does
  2. Google will soon be charging for the reCaptcha service
  3. hCaptcha will actually pay you for solves!

If you’re not convinced, read Cloudflare’s explanation of their decision to switch.

Anyway, the point of this post wasn’t going to be about that.  It was because I have been scratching my head for ages to figure out why my WP_Error response in my “pre_comment_approved” filter was just giving me a white screen, and no error message.

This is what I had…

return new WP_Error("captcha_invalid", "Error: Captcha invalid - are you human?"); 

I’d been checking through the comment code on Trac and could not figure it out.  Until I read line 3396.

return new WP_Error( 'comment_save_error', __( 'Error: The comment could not be saved. Please try again later.' ), 500 );

The third parameter is simply described in the WordPress code reference as “(mixed) (Optional) Error data. Default value: ” – not exactly enlightening.  But “500” certainly looked like an HTTP status code to me, so I tried “403” for mine…

return new WP_Error("captcha_invalid", "Error: Captcha invalid - are you human?", 403);

Bingo!  The error page appeared.  So I don’t know if it’s always required, but it certainly sorted out my problem today!