An expectedAction mismatch is a security signal, not a nuisance field to ignore. It means the action name attached to the token does not match the action your backend expected for the request it is assessing.
What expectedAction is supposed to protect
In reCAPTCHA Enterprise assessments, the backend can send an event with the token, siteKey, userAgent, user IP address, and expectedAction. Google's assessment response includes tokenProperties.action, and Google's docs say to verify that action matches expectedAction. If it does not, the docs frame that as a possible attempt to falsify actions.
That is the whole point of action names. A token generated for newsletter_signup should not be accepted for checkout_payment, and a token from a low-risk page should not be reused against a password reset endpoint. The backend action expectation binds the token to business intent.
The common mismatch patterns
The most common bug is spelling drift: the frontend calls grecaptcha.enterprise.execute(siteKey, {action: "passwordReset"}) while the backend expects password_reset. Another is route reuse: one API handler protects login, signup, and password reset but passes a hard-coded expectedAction of login for every request.
Mismatches can also appear during migrations. A React component may centralize execute() in a helper with a default action of submit, while the backend team adds precise expected actions. A/B tests and checkout refactors create the same problem when one path changes the frontend action string but the server contract stays old.
Instrument the comparison, not the secret
Log the route, expectedAction, returned tokenProperties.action, key ID or key label, environment, and deploy version. Do not log raw tokens, API keys, or user-specific values. If you need to correlate retries, hash the token or use an application request ID.
The fastest debugging view is a table grouped by route: expected action, actual action, count, first seen, last seen, frontend build, backend build. If one route shows submit versus checkout and another route is clean, you have a naming contract bug, not a global reCAPTCHA outage.
Fail or step up when the action is wrong
Do not repair this by accepting any returned action. That defeats the purpose of action binding and makes it easier to replay or misroute tokens. A safer pattern is: invalid token means fail; action mismatch means fail or step up; low score with matching action means apply your risk policy.
The user-facing retry path can be gentle. Preserve form data, refresh the token, and ask the user to submit again. Internally, treat repeated mismatches as a release bug or abuse signal until proven otherwise.
Make action names a shared contract
Keep action names in one shared constant list or contract document. Use names that describe the protected business event: login, signup, password_reset, checkout, cart_view, payment_add. Avoid one generic submit action across every flow because it collapses analytics and makes expectedAction less useful.
A small integration test can protect the contract. Render the frontend flow, intercept the action passed to execute(), send a test token through the backend assessment adapter, and assert that the backend expectedAction is the same string.
Sources and further reading
Google Cloud reCAPTCHA assessment docs for expectedAction, tokenProperties.action, and mismatch handling.
Google Cloud action names docs for recommended action names and monitoring value.
reCAPTCHA action names for a taxonomy teams can adopt before mismatches reach production.
Try rCAPTCHA on your own site
Start with a minimal free testing plan, add a real site key, and see per-site verification data before moving to a paid tier.