fix: Address review feedback for conversation status checking

- Add Note warning about production error handling at start of section
- Add raise_for_status() for HTTP error handling in all examples
- Use safe list access with len() checks to prevent IndexError
- Improve status documentation with actions for each state
- Add terminal states Note explaining which states exit polling loops
- Handle waiting_for_confirmation state in Complete Polling Example
- Handle ERROR status in start task polling loop

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

openhands/usage/cloud/cloud-api.mdx

@@ -171,6 +171,11 @@ Each update is streamed as it occurs, allowing you to provide real-time feedback
 
 After starting a conversation, you can check its status to monitor whether the agent has completed its task.
 
+<Note>
+  The examples below show basic polling patterns. For production use, add proper error handling, 
+  exponential backoff, and handle network failures gracefully.
+</Note>
+
 #### Step 1: Check Start Task Status
 
 When you start a conversation, you receive a start task ID. Poll this endpoint until `status` becomes `READY` and `app_conversation_id` is available:
@@ -218,12 +223,15 @@ Once you have the `app_conversation_id`, check whether the agent has finished it
         headers=headers,
         params={"ids": conversation_id}
     )
+    response.raise_for_status()  # Raise exception for HTTP errors
     conversations = response.json()
 
-    if conversations:
+    if conversations and len(conversations) > 0:
         conv = conversations[0]
         print(f"Sandbox Status: {conv.get('sandbox_status')}")
         print(f"Execution Status: {conv.get('execution_status')}")
+    else:
+        print("Conversation not found")
     ```
   </Tab>
 </Tabs>
@@ -244,20 +252,25 @@ Once you have the `app_conversation_id`, check whether the agent has finished it
 #### Status Fields
 
 **`sandbox_status`** - The state of the sandbox environment:
-- `STARTING` - Sandbox is being created
-- `RUNNING` - Sandbox is active
-- `PAUSED` - Sandbox is paused (due to rate limits or user action)
-- `ERROR` - Sandbox encountered an error
-- `MISSING` - Sandbox was deleted
+- `STARTING` - Sandbox is being created. **Action:** Continue polling.
+- `RUNNING` - Sandbox is active. **Action:** Check `execution_status` for task progress.
+- `PAUSED` - Sandbox is paused (due to rate limits or user action). **Action:** The sandbox will resume automatically when resources are available, or resume manually via the UI.
+- `ERROR` - Sandbox encountered an error. **Action:** This is a terminal state. Check conversation details in the UI for error information.
+- `MISSING` - Sandbox was deleted. **Action:** This is a terminal state. Start a new conversation if needed.
 
 **`execution_status`** - The state of the agent's task (available when sandbox is `RUNNING`):
-- `idle` - Agent is ready to receive tasks
-- `running` - Agent is actively working
-- `paused` - Execution is paused
-- `waiting_for_confirmation` - Agent is waiting for user confirmation
-- `finished` - Agent has completed the task
-- `error` - Agent encountered an error
-- `stuck` - Agent is stuck and unable to proceed
+- `idle` - Agent is ready to receive tasks. **Action:** Continue polling if task was recently submitted.
+- `running` - Agent is actively working. **Action:** Continue polling.
+- `paused` - Execution is paused. **Action:** Continue polling; will resume automatically.
+- `waiting_for_confirmation` - Agent is waiting for user confirmation. **Action:** This is a blocking state. The agent needs user input via the UI to proceed. Your polling loop should treat this as a terminal state or alert the user.
+- `finished` - Agent has completed the task. **Action:** Terminal state. Task is done successfully.
+- `error` - Agent encountered an error. **Action:** Terminal state. Check conversation in UI for error details.
+- `stuck` - Agent is stuck and unable to proceed. **Action:** Terminal state. Manual intervention may be required.
+
+<Note>
+  **Terminal states** that should exit your polling loop: `finished`, `error`, `stuck`, `waiting_for_confirmation`.
+  The `waiting_for_confirmation` state requires user action through the UI before the agent can continue.
+</Note>
 
 #### Complete Polling Example
 
@@ -287,6 +300,7 @@ start_response = requests.post(
         "selected_repository": "yourusername/your-repo"
     }
 )
+start_response.raise_for_status()
 start_task = start_response.json()
 task_id = start_task["id"]
 print(f"Start task ID: {task_id}")
@@ -301,12 +315,18 @@ while not conversation_id and attempts < max_attempts:
         headers=headers,
         params={"ids": task_id}
     )
+    task_response.raise_for_status()
     tasks = task_response.json()
-    if tasks and tasks[0].get("status") == "READY":
+    
+    if tasks and len(tasks) > 0 and tasks[0].get("status") == "READY":
         conversation_id = tasks[0].get("app_conversation_id")
         print(f"Conversation ready: {base_url}/conversations/{conversation_id}")
+    elif tasks and len(tasks) > 0 and tasks[0].get("status") == "ERROR":
+        print(f"Start task failed with error")
+        exit(1)
     else:
-        print(f"Start task status: {tasks[0].get('status') if tasks else 'unknown'}")
+        status = tasks[0].get("status") if tasks and len(tasks) > 0 else "no response"
+        print(f"Start task status: {status}")
         time.sleep(5)
         attempts += 1
 
@@ -315,6 +335,7 @@ if not conversation_id:
     exit(1)
 
 # Poll conversation until agent finishes (with timeout)
+# Terminal states: finished, error, stuck, waiting_for_confirmation
 max_attempts = 120  # 1 hour with 30-second intervals
 attempts = 0
 while attempts < max_attempts:
@@ -323,16 +344,27 @@ while attempts < max_attempts:
         headers=headers,
         params={"ids": conversation_id}
     )
+    conv_response.raise_for_status()
     conversations = conv_response.json()
 
-    if conversations:
-        conv = conversations[0]
-        exec_status = conv.get("execution_status")
-        print(f"Execution status: {exec_status}")
-        
-        if exec_status in ["finished", "error", "stuck"]:
-            print(f"Conversation completed with status: {exec_status}")
-            break
+    if not conversations or len(conversations) == 0:
+        print("Warning: Conversation not found")
+        time.sleep(30)
+        attempts += 1
+        continue
+    
+    conv = conversations[0]
+    exec_status = conv.get("execution_status")
+    print(f"Execution status: {exec_status}")
+    
+    # Check for terminal states
+    if exec_status in ["finished", "error", "stuck"]:
+        print(f"Conversation completed with status: {exec_status}")
+        break
+    elif exec_status == "waiting_for_confirmation":
+        print("Agent is waiting for user confirmation in the UI")
+        print(f"Visit: {base_url}/conversations/{conversation_id}")
+        break
 
     time.sleep(30)
     attempts += 1