Use the frm_captcha_error_message filter to change the message shown when a reCAPTCHA, hCaptcha, or Cloudflare Turnstile check fails. It receives the reason the CAPTCHA service gave and its error codes. Use them to show a different message for each kind of failure.

By default, the message doesn't say why the check failed. Telling a bot exactly why it was rejected helps it get past the next attempt. The one exception is a CAPTCHA that isn't set up correctly on your site, because a visitor can't fix that by trying again.

Requirements

• Formidable Forms 7.0 or later.
• The filter is in Formidable Forms Lite, so it works with or without Formidable Forms Pro.
• A CAPTCHA field on the form, with keys saved in Formidable → Global Settings → Captcha/Spam.

Usage

add_filter( 'frm_captcha_error_message', 'my_captcha_error_message', 10, 4 );

Parameters

• $message (string): The message shown on the CAPTCHA field. By default, this is the Invalid Format message in the field's Validation Messages options, or "The CAPTCHA was not entered correctly" when that box is empty. When the error codes show a site setup problem, it's "The CAPTCHA on this form is not set up correctly. Please contact the site administrator."
• $reason (string): A readable explanation of the failure, such as "The CAPTCHA response expired or was already used." For reCAPTCHA v3, it can also say that the score was below your threshold.
• $error_codes (array): The error codes returned by the CAPTCHA service, such as 'timeout-or-duplicate' or 'invalid-input-secret'. It can be empty.
• $field (array|object): The CAPTCHA field.

When the filter runs

The filter runs when the CAPTCHA service rejects a response, including a reCAPTCHA v3 score below the threshold. It doesn't run when the form is submitted without a CAPTCHA response, or when your site can't reach the CAPTCHA service. Those failures use their own messages.

The filtered message appears when the CAPTCHA errors spam check is set to Reject with an error message, which is the default.

When it's set to Save as a spam entry, a new submission is saved as a spam entry and no error is shown. When an existing entry is edited, the error still shows. Learn more about spam checks.

Examples

add_filter( 'frm_captcha_error_message', 'my_captcha_expired_message', 10, 3 );
function my_captcha_expired_message( $message, $reason, $error_codes ) {
	$expired_codes = array( 'timeout-or-duplicate', 'invalid-or-already-seen-response' );

	if ( array_intersect( $expired_codes, $error_codes ) ) {
		$message = 'The CAPTCHA expired. Please complete it again and resubmit the form.';
	}

	return $message;
}

add_filter( 'frm_captcha_error_message', 'my_show_captcha_reason_to_admins', 10, 2 );
function my_show_captcha_reason_to_admins( $message, $reason ) {
	if ( $reason && current_user_can( 'manage_options' ) ) {
		$message .= ' ' . $reason;
	}

	return $message;
}

Limitations

• Showing the reason to every visitor also shows it to bots. Instead, keep the detailed reason for administrators or for your own logs.
• The error codes differ between CAPTCHA services. In your function, check for every code you want to handle.

Related developer hooks

• Log or respond to every failed CAPTCHA check with the frm_captcha_validation_failed hook.
• Change the reCAPTCHA language with the frm_recaptcha_lang hook.

Related articles

• Add Spam Protection
• How to Set Up reCAPTCHA
• How to Set Up hCaptcha
• How to Set Up Cloudflare Turnstile