docs(faq): clarify encrypted PDF error handling and drag-drop flow

Author: lyzhang0113

_articles/faq/prompt-password-for-protected-pdf.md

@@ -15,16 +15,37 @@ last_modified: 2026-04-09 10:00:00 +0800
 ## How can I prompt users for a password when loading a password-protected PDF?
 
 Dynamic Web TWAIN does not provide a built-in password prompt UI for encrypted PDFs.  
-You need to implement your own prompt flow in application code.
+You need to handle the prompt and retry flow in your application code.
 
-### Recommended flow for `LoadImage()` / `LoadImageEx()`
+### Recommended workflow (`LoadImage()` / `LoadImageEx()`)
 
 1. Call [`LoadImage()`](/_articles/info/api/WebTwain_IO.md#loadimage) or [`LoadImageEx()`](/_articles/info/api/WebTwain_IO.md#loadimageex).
-2. In the failure callback, check whether `errorCode` is `-1119`.
+2. In the failure callback, treat the error as "password required" only when either condition is true:
+   - (`errorCode` is `-1119` and `errorString` contains  
+     `"Failed to read the PDF file because it's encrypted and the correct password is not provided."`)
+   - OR `errorCode` is `-1120`.
 3. Prompt the user for a password.
-4. Call [`SetReaderOptions()`](/_articles/info/api/Addon_PDF.md#setreaderoptions) with that password.
+4. Set the password via [`SetReaderOptions()`](/_articles/info/api/Addon_PDF.md#setreaderoptions).
 5. Retry loading the same PDF.
 
+### Helper function for password-required errors
+
+Use this helper in both API-based loading and drag-and-drop handling:
+
+```javascript
+function isPasswordRequired(errorCode, errorString) {
+    return (
+        (errorCode === -1119 &&
+            (errorString || "").includes(
+                "Failed to read the PDF file because it's encrypted and the correct password is not provided.",
+            )) ||
+        errorCode === -1120
+    );
+}
+```
+
+### `LoadImage()` / `LoadImageEx()` example
+
 ```javascript
 function loadProtectedPdf(path, password) {
     DWTObject.Addon.PDF.SetReaderOptions({ password: password || "" });
@@ -35,7 +56,7 @@ function loadProtectedPdf(path, password) {
             console.log("PDF loaded successfully.");
         },
         function (errorCode, errorString) {
-            if (errorCode !== -1119) {
+            if (!isPasswordRequired(errorCode, errorString)) {
                 console.error(errorCode, errorString);
                 return;
             }
@@ -52,20 +73,35 @@ function loadProtectedPdf(path, password) {
 }
 ```
 
-### For drag-and-drop files
+### Drag-and-drop workflow (`OnPostLoad`)
 
-You can detect load failures in [`OnPostLoad`](/_articles/info/api/WebTwain_IO.md#onpostload) by checking `DWTObject.ErrorCode` and `DWTObject.ErrorString`.
+Use [`OnPostLoad`](/_articles/info/api/WebTwain_IO.md#onpostload) and check `DWTObject.ErrorCode` / `DWTObject.ErrorString`.
 
 ```javascript
 DWTObject.RegisterEvent("OnPostLoad", function (path, name, type) {
-    if (DWTObject.ErrorCode === -1119) {
-        console.log(DWTObject.ErrorString);
-        // Add your own password prompt flow here.
+    if (!isPasswordRequired(DWTObject.ErrorCode, DWTObject.ErrorString)) return;
+
+    var userPassword = window.prompt(
+        "This PDF is password-protected. Please enter the password:",
+        "",
+    );
+    if (!userPassword) return;
+
+    DWTObject.Addon.PDF.SetReaderOptions({ password: userPassword });
+
+    if (!path) {
+        alert("Password saved. Please drag and drop the file again.");
+        return;
     }
+
+    var fullPath = path + "\\" + name;
+    loadProtectedPdf(fullPath, userPassword);
 });
 ```
 
 > [!NOTE]
-> In `OnPostLoad`, `path` is empty for drag-and-drop files.
-> If you need a retry flow after entering a password, prompt the user to select the file again
-> (for example, by using [`ShowFileDialog()`](/_articles/info/api/WebTwain_IO.md#showfiledialog) + [`LoadImageEx()`](/_articles/info/api/WebTwain_IO.md#loadimageex)).
+> `-1119` can represent multiple PDF load issues, so do not use it alone.
+> Starting in Dynamic Web TWAIN 19.4, encrypted-PDF load failures will use `-1120`.
+>
+> In `OnPostLoad`, `path` is empty for drag-and-drop files, so the code cannot directly retry with a file path.
+> In this case, prompt for password, save it with `SetReaderOptions()`, and ask the user to drag and drop the file again.