Use the frm_captcha_validation_failed action to run your own code when a reCAPTCHA, hCaptcha, or Cloudflare Turnstile check fails. It receives the reason for the failure and the error codes from the CAPTCHA service. Use it to log failures or to alert someone when the CAPTCHA isn't set up correctly.

Requirements

• Formidable Forms 7.0 or later.
• The action is in Formidable Forms Lite. 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_action( 'frm_captcha_validation_failed', 'my_captcha_validation_failed', 10, 4 );

Parameters

• $reason (string): A readable explanation of the failure, such as "The CAPTCHA response expired or was already used."
• $error_codes (array): The error codes returned by the CAPTCHA service, such as 'timeout-or-duplicate'. It can be empty.
• $form_id (int): The ID of the form being submitted.
• $field (array|object): The CAPTCHA field.

When the action runs

The action runs in each of these cases:

• No CAPTCHA response: The form was submitted without a CAPTCHA response, for example before the CAPTCHA loaded. $error_codes is array( 'missing-input-response' ).
• Service can't be reached: Your site couldn't connect to the CAPTCHA service. $reason is the connection error and $error_codes is empty.
• Response rejected: The CAPTCHA service rejected the response. This includes a reCAPTCHA v3 score below your threshold.

It runs before Formidable applies the CAPTCHA errors spam check. So it fires whether that check is set to Save as a spam entry or Reject with an error message.

When the submission is saved as a spam entry, the reason and error codes are saved with it. Learn more about spam checks.

Examples

add_action( 'frm_captcha_validation_failed', 'my_log_captcha_failures', 10, 3 );
function my_log_captcha_failures( $reason, $error_codes, $form_id ) {
	error_log(
		sprintf(
			'CAPTCHA failed on form %d: %s (%s)',
			$form_id,
			$reason,
			$error_codes ? implode( ', ', $error_codes ) : 'no codes'
		)
	);
}

add_action( 'frm_captcha_validation_failed', 'my_alert_on_captcha_setup_error', 10, 3 );
function my_alert_on_captcha_setup_error( $reason, $error_codes, $form_id ) {
	$setup_codes = array(
		'missing-input-secret',
		'invalid-input-secret',
		'bad-request',
		'invalid-sitekey',
		'sitekey-secret-mismatch',
		'not-using-dummy-passcode',
		'not-using-dummy-secret',
		'invalid-widget-id',
		'invalid-parsed-secret',
	);

	if ( ! array_intersect( $setup_codes, $error_codes ) || get_transient( 'my_captcha_setup_alert_sent' ) ) {
		return;
	}

	wp_mail(
		get_option( 'admin_email' ),
		'CAPTCHA setup problem',
		sprintf( 'A CAPTCHA check failed on form %d: %s', $form_id, $reason )
	);

	set_transient( 'my_captcha_setup_alert_sent', 1, HOUR_IN_SECONDS );
}

Limitations

• The action can't change the error message or stop the failure. To change the message, use the frm_captcha_error_message filter.
• The error codes differ between CAPTCHA services. Check for every code you want to handle.

Related developer hooks

• Change the message shown when a CAPTCHA check fails with the frm_captcha_error_message 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