# AI Qualification Troubleshooting Guide

**Document Version:** 1.0.0 (Phase 12)

---

## Common Issues & Resolutions

### 1. "AI qualification is disabled for this workspace"
- **Cause:** `workspaces.ai_enabled` is set to `false`.
- **Resolution:** Navigate to `/settings/ai` and toggle "Enable AI Qualification" to **Enabled**.

### 2. "Too many AI analysis requests. Please wait a minute and try again."
- **Cause:** Rate limit exceeded (10 requests per minute per user).
- **Resolution:** Wait 60 seconds before triggering another manual re-analysis.

### 3. Lead shows "fallback" provider or default scores
- **Cause:** OpenAI API key not configured or provider timed out.
- **Resolution:** Check `.env` configuration for `OPENAI_API_KEY`. In offline testing environments, LeadPilot automatically activates deterministic rule scoring.

### 4. Cross-Workspace Access Denied (403/404)
- **Cause:** User attempted to qualify a lead belonging to another workspace.
- **Resolution:** Ensure the active session context matches the lead's workspace.