Fix ConnectError handling in Telegram bot API client

Fix AttributeError crash when backend is unreachable during account linking.
Previously, when telegram bot couldn't connect to backend, the error handler
tried to access e.response.status_code on a ConnectError exception which
doesn't have a response attribute.

Changes to reports-app/telegram-bot/app/api/client.py:
- Import ConnectError from httpx
- Add separate exception handler for ConnectError before HTTPError handler
- Log clear error message indicating backend connectivity issue
- Return None gracefully instead of crashing with AttributeError

Changes to deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md:
- Add new section "Problem: Cannot connect to backend / Connection Errors"
- Add diagnostic steps for backend service verification
- Add checklist for BACKEND_URL configuration (http://localhost:8000)
- Add Issue 5: Backend Service Not Running
- Add Issue 6: Wrong Backend URL in Telegram Bot
- Include PowerShell commands for Windows Server troubleshooting

This fix ensures the Telegram bot provides clear error messages when backend
is unavailable instead of crashing, making debugging easier for production
deployments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md

@@ -169,6 +169,150 @@ Fix the issue by following this checklist in order:
   - Send code to @ROA2WEBBot via `/start CODE12345`
   - Should receive success message from bot
 
+---
+
+## Problem: "Cannot connect to backend" / Connection Errors
+
+After successfully generating a linking code, the Telegram bot finds the code but fails to complete the linking with error messages like:
+
+- `httpcore.ConnectError: All connection attempts failed`
+- `Cannot connect to backend at http://localhost:8000`
+- `AttributeError: 'ConnectError' object has no attribute 'response'` (fixed in latest version)
+
+### Root Cause
+
+The Telegram bot cannot communicate with the FastAPI backend to verify the Oracle user and obtain a JWT token. This happens when:
+
+1. Backend service is not running
+2. Backend is running on wrong port
+3. BACKEND_URL in telegram bot .env is incorrect
+4. Firewall blocking communication
+
+### Diagnostic Steps
+
+#### 1. Check Backend Service Status
+
+```powershell
+# Check if backend service is running
+Get-Service ROA2WEB-Backend
+
+# Expected output:
+# Status   Name              DisplayName
+# ------   ----              -----------
+# Running  ROA2WEB-Backend   ROA2WEB Backend Service
+```
+
+If service is **not running**, start it:
+```powershell
+cd C:\inetpub\wwwroot\roa2web\scripts
+.\Start-ROA2WEB.ps1
+```
+
+#### 2. Check Backend Port (8000)
+
+```powershell
+# Check if port 8000 is listening
+netstat -ano | findstr :8000
+
+# Expected output (should show LISTENING):
+# TCP    0.0.0.0:8000    0.0.0.0:0    LISTENING    <PID>
+```
+
+If port is **not listening**, check backend logs:
+```powershell
+# View backend service logs
+Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50
+```
+
+#### 3. Test Backend Health Endpoint
+
+```powershell
+# Test if backend API responds
+Invoke-WebRequest http://localhost:8000/health
+
+# Expected output:
+# StatusCode        : 200
+# Content           : {"status":"healthy",...}
+```
+
+If this **fails**, backend is not accessible. Check service logs.
+
+#### 4. Check Telegram Bot BACKEND_URL Configuration
+
+```powershell
+# View telegram bot .env file
+notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
+
+# Verify this line exists and is correct:
+# BACKEND_URL=http://localhost:8000
+```
+
+**Common mistakes:**
+- Using `http://localhost:8001` (dev port instead of production port 8000)
+- Missing `http://` prefix
+- Using IP address instead of localhost
+
+If BACKEND_URL is **incorrect**, fix it and restart:
+```powershell
+cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
+.\Restart-TelegramBot.ps1
+```
+
+#### 5. Test Backend Verify-User Endpoint
+
+```powershell
+# Test the specific endpoint telegram bot uses
+Invoke-WebRequest -Method POST -Uri http://localhost:8000/api/telegram/auth/verify-user `
+  -Headers @{"Content-Type"="application/json"} `
+  -Body '{"linking_code":"TESTCODE","oracle_username":"testuser"}'
+
+# Expected output (will fail with 400/404 for test data, but confirms endpoint is reachable):
+# StatusCode: 400 or 404 (NOT connection error)
+```
+
+If you get **connection error** instead of 400/404, backend is not running or port is wrong.
+
+### Solution Checklist
+
+Fix the issue by following this checklist:
+
+- [ ] **Backend service is running**
+  ```powershell
+  Get-Service ROA2WEB-Backend
+  # If stopped: cd C:\inetpub\wwwroot\roa2web\scripts; .\Start-ROA2WEB.ps1
+  ```
+
+- [ ] **Backend port 8000 is listening**
+  ```powershell
+  netstat -ano | findstr :8000
+  # Should show LISTENING on 0.0.0.0:8000
+  ```
+
+- [ ] **Backend health check responds**
+  ```powershell
+  Invoke-WebRequest http://localhost:8000/health
+  # Should return 200 OK
+  ```
+
+- [ ] **Telegram bot .env has correct BACKEND_URL**
+  ```powershell
+  notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
+  # Must be: BACKEND_URL=http://localhost:8000
+  ```
+
+- [ ] **Telegram bot service restarted after .env changes**
+  ```powershell
+  cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
+  .\Restart-TelegramBot.ps1
+  ```
+
+- [ ] **Test full linking flow**
+  - Generate code in web frontend
+  - Send code to @ROA2WEBBot: `/start CODE12345`
+  - Should receive success message (not connection error)
+
+---
+
 ### Common Issues
 
 #### Issue 1: Port 8002 Already in Use
@@ -240,6 +384,60 @@ Start-Sleep -Seconds 10
 .\Start-TelegramBot.ps1
 ```
 
+#### Issue 5: Backend Service Not Running
+
+**Symptoms:**
+- Telegram bot logs show "Cannot connect to backend" errors
+- `httpcore.ConnectError: All connection attempts failed`
+- Linking codes are found but linking fails
+
+**Solution:**
+```powershell
+# Check backend service status
+Get-Service ROA2WEB-Backend
+
+# If stopped, start it
+cd C:\inetpub\wwwroot\roa2web\scripts
+.\Start-ROA2WEB.ps1
+
+# Verify backend is listening on port 8000
+netstat -ano | findstr :8000
+
+# Test backend health
+Invoke-WebRequest http://localhost:8000/health
+```
+
+**Check backend logs for startup errors:**
+```powershell
+Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50
+```
+
+**Common backend startup issues:**
+- Oracle database not accessible
+- Missing environment variables in backend `.env`
+- Port 8000 already in use by another process
+- Python dependencies not installed
+
+#### Issue 6: Wrong Backend URL in Telegram Bot
+
+**Symptoms:**
+- Connection errors to backend
+- Logs show wrong URL (e.g., `http://localhost:8001` instead of `http://localhost:8000`)
+
+**Solution:**
+```powershell
+# Edit telegram bot .env
+notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
+
+# Ensure this line is correct:
+# BACKEND_URL=http://localhost:8000
+# (Production uses port 8000, not 8001 which is dev port)
+
+# Restart telegram bot service
+cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
+.\Restart-TelegramBot.ps1
+```
+
 ### Verification Steps
 
 After fixing, verify the complete flow works:

reports-app/telegram-bot/app/api/client.py

@@ -11,7 +11,7 @@ from typing import Optional, Dict, Any, List
 from datetime import datetime
 
 import httpx
-from httpx import AsyncClient, Response, HTTPError
+from httpx import AsyncClient, Response, HTTPError, ConnectError
 
 logger = logging.getLogger(__name__)
 
@@ -144,6 +144,10 @@ class BackendAPIClient:
 
             return await self._handle_response(response)
 
+        except ConnectError as e:
+            logger.error(f"Cannot connect to backend at {self.base_url}: {e}")
+            logger.error("Verify that backend service is running and BACKEND_URL is correct")
+            return None
         except HTTPError as e:
             if e.response.status_code == 404:
                 logger.warning(f"User {oracle_username} not found in Oracle")