ClassifyDocumentAsync WaitForCompletion hangs with no timeout

Hi Jack Halpern,
Azure.AI.FormRecognizer SDK (v4.1.0), it’s important to note that the SDK does not expose a built-in timeout for the polling operation. If the service does not return a response (for example, due to a throttling condition, network issue, or long-running job), the call can appear to hang indefinitely. To handle this, we recommend wrapping the operation in your own timeout or cancellation logic using a CancellationToken. This allows you to force the polling loop to stop after a defined period of time, ensuring your thread does not block forever.

Regarding throttling, if you exceed the transaction-per-second limit on your pricing tier, the service should normally return a 429 Too Many Requests error. If you are not seeing 429s, the issue may be related to network reliability, transient errors, or a stalled service request. To better diagnose this, you can enable SDK logging or capture network traces to see the actual REST API calls being made and whether a response is ever returned. This will help confirm if throttling is happening or if another condition is causing the stall.

As a best practice, we recommend always implementing retry logic with exponential backoff, along with timeouts or cancellation tokens around long-running operations like WaitForCompletionAsync. This ensures that your application remains resilient against both transient failures and unexpected hangs. Additionally, monitoring the metrics in your Form Recognizer resource in the Azure Portal (such as call volume, errors, and latency) can give further insights into whether you are being throttled or encountering another bottleneck.

Thanks for the response. I will work on wrapping the calls using the CancellationToken as you suggest. In the meanwhile, I reviewed the metrics in our resource and saw nothing which would indicate any errors. Can you be more specific about what metrics I should be looking at or how else to investigate what occurred around this time? Or perhaps link to Azure documentation which might help?

Thanks

Jack

Hi Jack Halpern,
To investigate why your WaitForCompletionAsync call might hang, you should start by checking a few key metrics in your Form Recognizer resource on the Azure Portal. Review the number of transactions per second to confirm you are not exceeding the 15 TPS limit of the Standard (S0) tier. Also check the count of throttled requests, which would indicate if the service is rejecting calls due to overload, and look at any server errors (5xx status codes) that may point to service-side problems. Finally, monitor the latency metric to see if requests are taking much longer than expected.

If these metrics do not show any issues, the next step is to enable diagnostic logging in your application or use network tracing tools. This will let you capture the actual HTTP calls made by the SDK and confirm whether requests are stuck waiting for a response or if an error occurred silently.

On the application side, it is a best practice to wrap WaitForCompletionAsync with a cancellation token that includes a timeout. This ensures your thread will not hang indefinitely and gives you control over how long to wait for a response. In addition, applying retry logic with exponential backoff will make your application more resilient to temporary service or network interruptions.

By combining monitoring of metrics, diagnostic logging, cancellation handling, and retries, you will have a more reliable integration and a clear path to diagnosing what is happening when hangs occur.

Hi Jack Halpern,
Did you get any chance to check the response. Thank you!

Hi Jack Halpern,
Just following up to see if you had a chance to review the above response. Thank you!