Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Solução de problemas na integração do Identity Platform com a API reCAPTCHA Enterprise
Este documento oferece orientações para resolver possíveis problemas que podem
ocorrer ao usar a integração do Identity Platform com a API reCAPTCHA Enterprise, incluindo a
proteção contra bots do reCAPTCHA e os recursos de defesa do reCAPTCHA SMS.
Solução de problemas de integração
Seus usuários podem estar enfrentando problemas devido a erros na integração
da Identity Platform com a API reCAPTCHA Enterprise. Alguns motivos comuns incluem:
Talvez você tenha pulado uma etapa na integração da Identity Platform com a configuração da API reCAPTCHA Enterprise. Por
exemplo, se você não configurar a conta de serviço ou ativar a
API reCAPTCHA Enterprise no projeto. Verifique se você cumpriu todos
os requisitos de integração. Para instruções de configuração, consulte Integrar a
plataforma de identidade com a API reCAPTCHA
Enterprise.
Se você usar sua própria chave com o reCAPTCHA, a chave reCAPTCHA correspondente que você enviou pode não ser válida ou pode ter parado de funcionar. Verifique se a
chave está funcionando e acessível pelo Identity Platform.
Os usuários podem estar usando uma versão desatualizada do app. Forneça uma
versão atualizada do app que use o SDK do cliente e peça aos usuários
que atualizem o app. Para configurar o SDK do cliente para o app, consulte Configurar
o
SDK do cliente.
Os usuários não conseguem fazer a autenticação nos fluxos compatíveis com a API reCAPTCHA Enterprise
Se você tiver problemas com fluxos com suporte à API reCAPTCHA Enterprise, como a proteção contra bots ou a defesa por SMS do reCAPTCHA, consulte as seções a seguir para receber orientações específicas sobre o recurso.
Solução de problemas da proteção contra bots do reCAPTCHA
Os tópicos a seguir descrevem possíveis problemas que você pode encontrar ao usar a proteção contra bots e como resolvê-los.
Os usuários não conseguem fazer a autenticação ao usar a proteção contra bots para provedores de e-mail/senha ou telefone
Se você determinou que a integração do Identity Platform com a API reCAPTCHA Enterprise foi configurada corretamente,
os usuários podem ser bloqueados para realizar ações de autenticação por provedores de e-mail e senha ou de telefone com base na sua configuração atual. Por
exemplo, os usuários podem não conseguir realizar as seguintes ações:
Faça login, cadastre-se ou redefina uma senha usando um endereço de e-mail.
Solicitar um código por SMS para fazer login usando um número de telefone.
Faça o registro ou o login com a autenticação multifator por SMS.
Para resolver esses problemas de autenticação, tente o seguinte:
Se as solicitações do usuário falharem com ERROR_CAPTCHA_CHECK_FAILED, considere uma
configuração mais permissiva ajustando os limites que você definiu para
managedRules. Todas as solicitações com pontuação abaixo do limite definido serão
consideradas bots. Por exemplo, se você definir um limite de 0.6,
o reCAPTCHA vai falhar em qualquer solicitação com 0.5 ou inferior.
Portanto, quanto maior a pontuação, mais rígidas serão as regras.
Peça para o usuário tentar usar um dispositivo, navegador ou rede diferente.
Retorne ao modo de auditoria e monitore as métricas antes de reativar o modo de aplicação.
Solução de problemas do reCAPTCHA SMS Defense
Os tópicos a seguir descrevem possíveis problemas que você pode encontrar ao usar a defesa do SMS do reCAPTCHA e como resolvê-los.
Os usuários não conseguem fazer a autenticação ao usar a defesa de SMS do reCAPTCHA para o provedor de telefonia
Se você determinou que a integração do Identity Platform com a API reCAPTCHA Enterprise foi configurada corretamente,
os usuários podem ser bloqueados de realizar ações de autenticação por SMS pelo
provedor de telefonia com base na sua configuração atual. Por exemplo, os usuários podem
não conseguir solicitar um código de SMS para fazer login com um número de telefone ou se inscrever ou
fazer login com a autenticação multifator. Isso pode acontecer se a
pontuação de defesa de SMS do reCAPTCHA definida for muito rigorosa.
Para resolver esse problema, considere uma configuração mais permissiva ajustando o
limite definido para tollFraudManagedRules. Qualquer pontuação acima do limite
definido será considerada fraude de SMS. Por exemplo, se você definir um limite
de 0.3, o reCAPTCHA vai falhar em qualquer solicitação com 0.4 ou mais.
Portanto, quanto menor a pontuação, mais rígidas serão as regras.
Se isso for um problema, recomendamos definir o modo de aplicação como auditoria para testar
e monitorar as métricas do reCAPTCHA emitidas pelo seu projeto. Isso
vai ajudar a garantir que seu app esteja recebendo tráfego de usuário aceitável antes de
ativar a aplicação de políticas novamente.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[[["\u003cp\u003eThis document offers guidance on troubleshooting issues with the Identity Platform integration with the reCAPTCHA Enterprise API, which includes bot protection and SMS toll fraud protection.\u003c/p\u003e\n"],["\u003cp\u003eCommon issues during onboarding can stem from missed setup steps, like neglecting to set up the service account or using an invalid reCAPTCHA key, or if users are using outdated app versions.\u003c/p\u003e\n"],["\u003cp\u003eUsers might face authentication failures due to strict configurations; adjusting the \u003ccode\u003emanagedRules\u003c/code\u003e thresholds in bot protection or the \u003ccode\u003etollFraudManagedRules\u003c/code\u003e thresholds in SMS toll fraud protection can resolve these issues.\u003c/p\u003e\n"],["\u003cp\u003eWhen encountering authentication issues, you can ask users to try a different device, browser, or network, or revert to audit mode to monitor metrics before re-enabling enforcement mode.\u003c/p\u003e\n"],["\u003cp\u003eIf SMS toll fraud protection is blocking authentication, consider lowering the score threshold to be more permissive, and use audit mode to test and monitor metrics.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting the Identity Platform integration with the reCAPTCHA Enterprise API\n===================================================================================\n\nThis document provides guidance for troubleshooting potential issues that might\narise when using the Identity Platform integration with the reCAPTCHA Enterprise API, including the\nreCAPTCHA bot protection and reCAPTCHA SMS defense features.\n\nIntegration onboarding troubleshooting\n--------------------------------------\n\nYour users might be experiencing issues due to mistakes when onboarding\nwith the Identity Platform integration with the reCAPTCHA Enterprise API. Some common reasons might include the\nfollowing:\n\n- You might have missed a step in the Identity Platform integration with the reCAPTCHA Enterprise API set up. For example, neglecting to set up the service account or enabling the reCAPTCHA Enterprise API on the project. Ensure you've completed all the integration requirements. For set up instructions, see [Integrate\n Identity Platform with the reCAPTCHA Enterprise\n API](/identity-platform/docs/recaptcha-enterprise).\n- If you are [bringing your own key](/identity-platform/docs/recaptcha-byok) to use with reCAPTCHA, the corresponding reCAPTCHA key you uploaded might not be valid or might have stopped working. Verify that the key is working and accessible by Identity Platform.\n- Users might be using an outdated version of your app. Make sure you provide an updated version of your app that uses the client SDK, and ask your users to update their app. To set up the client SDK for your app, see [Configure\n the\n client SDK](/identity-platform/docs/recaptcha-enterprise#configure-sdk).\n\nUsers can't authenticate through reCAPTCHA Enterprise API supported flows\n-------------------------------------------------------------------------\n\nIf you are experiencing issues with reCAPTCHA Enterprise API supported\nflows, such as reCAPTCHA bot protection or reCAPTCHA SMS defense, see the\nfollowing sections for feature specific guidance.\n\n### reCAPTCHA bot protection troubleshooting\n\nThe following topics describe possible issues that you might face when using\nbot protection and how you might solve them.\n\n#### Users can't authenticate when using bot protection for the email-password or phone providers\n\nIf you have determined that the Identity Platform integration with the reCAPTCHA Enterprise API was set up correctly,\nusers might be blocked from performing authentication actions through the\nemail-password or phone providers based on your current configuration. For\nexample, users might be unable to perform the following actions:\n\n- Sign-in, sign-up, or reset a password through an email address.\n- Request an SMS code to sign in through a phone number.\n- Enroll in or sign in with SMS-based multi-factor authentication.\n\nTo resolve these authentication issues, try the following:\n\n- If user requests are failing with `ERROR_CAPTCHA_CHECK_FAILED`, consider a more permissive configuration by adjusting the thresholds you've set for `managedRules`. Any requests that score below the threshold you set will be considered a bot. For example, if you set a threshold of `0.6`, reCAPTCHA will fail any request with a `0.5` or lower. Therefore, the higher you set the score, the stricter the rules will be.\n- Ask the user to try a different device, browser, or network.\n- Revert to audit mode and monitor metrics before re-enabling enforcement mode.\n\n### reCAPTCHA SMS defense troubleshooting\n\nThe following topics describe possible issues you might face when using\nreCAPTCHA SMS defense and how you might solve them.\n\n#### Users can't authenticate when using reCAPTCHA SMS defense for the phone provider\n\nIf you have determined that the Identity Platform integration with the reCAPTCHA Enterprise API was set up correctly,\nusers might be blocked from performing SMS-based authentication actions through\nthe phone provider based on your current configuration. For example, users might\nbe unable to request an SMS code to sign in with a phone number or enroll in or\nsign in with multi-factor authentication. This can happen if the\nreCAPTCHA SMS defense score you set is too strict.\n\nTo resolve this, consider a more permissive configuration by adjusting the\nthreshold you've set for `tollFraudManagedRules`. Any score above the threshold\nyou set will be considered SMS toll fraud. For example, if you set a threshold\nof `0.3`, reCAPTCHA will fail any request with a `0.4` or higher.\nTherefore, the lower you set the score, the stricter the rules will be.\n\nIf this is an issue, we recommend setting your enforcement mode to audit to test\nand monitor the reCAPTCHA metrics emitted by your project. This\nwill help you ensure that your app is receiving acceptable user traffic before\nenabling enforcement again.\n\nWhat's next\n-----------\n\n- Learn more about [monitoring reCAPTCHA\n metrics](/identity-platform/docs/recaptcha-metrics)."]]
