# Error Signals | Developer Documentation

<div id="bkmrk-error-signalsupdated">## Error Signals

<div><span>Updated: Feb 6, 2026</span></div><div><div>**Upcoming deprecation:** Starting **April 15, 2026**, the `PendingIntent`-based handshake method for authentication templates will be deprecated. If you are currently using `PendingIntent` to initiate handshakes or verify app identity, the [OTP Android SDK](/books/meta-whatsapp/page/zero-tap-authentication-templates-developer-documentation) is the preferred way to migrate.</div></div><div><div>The OTP Android SDK features a simplified workflow for implementing one-tap and zero-tap authentication templates. You can learn how to use it below.</div></div><div>This document describes Android-only error signals that can help you debug [one-tap autofill authentication templates](/books/meta-whatsapp/page/one-tap-autofill-authentication-templates-developer-documentation) and [zero-tap authentication templates](/books/meta-whatsapp/page/zero-tap-authentication-templates-developer-documentation).</div><div>If your message fails the eligibility check, the one-tap autofill button will be replaced with a copy code button. In addition, there may be device or WhatsApp client settings that prevent message notifications. To help with debugging, our apps surface some error information via the `com.whatsapp.OTP_ERROR` intent. In these situations you will receive an error key and message instead of the user’s one-time passwords or verification code.</div><div>Note that some of these error signals will only surface if you are running WhatsApp in the Android emulator.</div><div><table><thead><tr><th><span>Key </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`ambiguous_delivery_destination`</div><div>*Emulator only*</div></div></td><td><div><div>**Ambiguous delivery destination**</div><div>There are multiple active OTP requests for the packages specified by this template, and we could not determine which package to deliver the code to.</div><div>This can happen when multiple applications specified in the template’s `supported_apps` array have initiated the handshake (sent the `com.whatsapp.otp.OTP_REQUESTED` intent) within the past 10 minutes.</div></div></td></tr><tr><td><div><div>`incompatible_os_version`</div></div></td><td><div><div>**Incompatible Android version**</div><div>  
This can happen when you initiate the handshake (send the `com.whatsapp.otp.OTP_REQUESTED` intent) but the device is running a version of Android older than v19.</div></div></td></tr><tr><td><div><div>`incorrect_signature_hash`</div><div>*Emulator only*</div></div></td><td><div><div>**Incorrect signature hash**</div><div>  
This can happen when you initiate the handshake (send the `com.whatsapp.otp.OTP_REQUESTED` intent) and our app receives an authentication template message that uses a one-tap autofill button, but the package name in the message does not produce the message’s signature hash.</div></div></td></tr><tr><td><div><div>`missing_handshake_or_disorder`</div></div></td><td><div><div>**Missing handshake / Order of operations**</div><div>  
This can happen when our app receives an authentication template message with a one-tap autofill button but the handshake was not initiated.</div></div></td></tr><tr><td><div><div>`otp_request_expired`</div></div></td><td><div><div>**OTP request expired**</div><div>  
This can happen when an authentication template that uses a one-tap autofill button is delivered to the user but more than 10 minutes (or the number of minutes indicated in the template’s `code_expiration_minutes` property, if present) have passed since you initiated the handshake. In this situation, we display the copy code button instead.</div></div></td></tr><tr><td><div><div>`whatsapp_message_notification_disabled`</div><div>*Emulator only*</div></div></td><td><div><div>**Message notification disabled in WA settings**</div><div>  
This can happen when you initiate the handshake (send the `com.whatsapp.otp.OTP_REQUESTED` intent) but the user has disabled notifications in the WhatsApp app or WhatsApp Business app (within our app settings).</div></div></td></tr><tr><td><div><div>`whatsapp_notification_disabled`</div><div>*Emulator only*</div></div></td><td><div><div>**WA notification disabled in device level**</div><div>  
This can happen when you initiate the handshake (send the `com.whatsapp.otp.OTP_REQUESTED` intent) but the user has disabled app notifications for our apps (device level settings).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-integration"><div id="bkmrk-integration-1"><div>#### Integration

</div></div></div><div>The error signals are delivered via broadcasted intent so you must implement [`BroadcastReceiver`<span>⁠</span>](https://l.facebook.com/l.php?u=https%3A%2F%2Fdeveloper.android.com%2Freference%2Fandroid%2Fcontent%2FBroadcastReceiver&h=AT4q1RHNaJfjSsir9UNvGDxY4-HhwpaY6fOkDZsIpDJHKMOwNP-nZcaAdhaI9KzfEGZB9Jw-VMrO1bBrJ7ADuvmNXRAuZRituKcRtJxQXGp0-0U4cCe-_AFGd5ll08W0401dWbGJyxnEK4YvCN5frA) to listen for error signals.</div><div id="bkmrk-in-manifest.xml"><div id="bkmrk-in-manifest.xml-1"><div>##### In manifest.xml

</div></div></div><div><div>```
<receiver
 android:name=".app.otp.OtpErrorReceiver"
 android:enabled="true"
 android:exported="true" >
   <intent-filter>
       <action android:name="com.whatsapp.otp.OTP_ERROR"/>
   </intent-filter>
</receiver>
```

</div></div><div id="bkmrk-receiver-class---usi"><div id="bkmrk-receiver-class---usi-1"><div>##### Receiver class - Using the SDK (Preferred)

</div></div></div><div>Implement `onReceive` and use a `WhatsAppOtpIncomingIntentHandler` object to process the debug signals.</div><div>```
<span>public</span><span>class</span><span>OtpErrorReceiver</span><span>extends</span><span>BroadcastReceiver</span><span>{</span><span>@Override</span><span>public</span><span>void</span><span> onReceive</span><span>(</span><span>Context</span><span> context</span><span>,</span><span>Intent</span><span> intent</span><span>)</span><span>{</span><span>WhatsAppOtpIncomingIntentHandler</span><span> whatsAppOtpIncomingIntentHandler </span><span>=</span><span>new</span><span>WhatsAppOtpIncomingIntentHandler</span><span>();</span><span>
     whatsAppOtpIncomingIntentHandler</span><span>.</span><span>processOtpDebugSignals</span><span>(</span><span>
                          intent</span><span>,</span><span>// your function to handle the signal</span><span>(</span><span>debugSignal</span><span>)</span><span>-></span><span> handleSignal</span><span>(</span><span>debugSignal</span><span>),</span><span>// your function to handle any error</span><span>(</span><span>error</span><span>,</span><span> exception</span><span>)</span><span>-></span><span> handleError</span><span>(</span><span>error</span><span>,</span><span> exception</span><span>));</span><span>}</span><span>}</span>
```

</div><div id="bkmrk-receiver-class---wit"><div id="bkmrk-receiver-class---wit-1"><div>##### Receiver class - Without the SDK

</div></div></div><div>```
<span>public</span><span>class</span><span>OtpErrorReceiver</span><span>extends</span><span>BroadcastReceiver</span><span>{</span><span>public</span><span>static</span><span>final</span><span>String</span><span> OTP_ERROR_KEY </span><span>=</span><span>"error"</span><span>;</span><span>public</span><span>static</span><span>final</span><span>String</span><span> OTP_ERROR_MESSAGE_KEY </span><span>=</span><span>"error_message"</span><span>;</span><span>@Override</span><span>public</span><span>void</span><span> onReceive</span><span>(</span><span>Context</span><span> context</span><span>,</span><span>Intent</span><span> intent</span><span>)</span><span>{</span><span>String</span><span> otpErrorKey </span><span>=</span><span> intent</span><span>.</span><span>getStringExtra</span><span>(</span><span>OTP_ERROR_KEY</span><span>);</span><span>String</span><span> otpErrorMessage </span><span>=</span><span> intent</span><span>.</span><span>getStringExtra</span><span>(</span><span>OTP_ERROR_MESSAGE_KEY</span><span>);</span><span>// Handle errors</span><span>}</span><span>}</span>
```

</div></div>