# Vision API Troubleshooting Improvements

**Last Updated:** 2026-01-19

## Overview

Enhanced error handling and diagnostics to help identify and resolve common Vision API issues, particularly API key restrictions which are the most common cause of 403 SERVICE_DISABLED errors.

## Improvements Made

### 1. Enhanced Error Messages

**File:** `v2/api/ocr-business-card.php`

- Added comprehensive troubleshooting steps to 403 SERVICE_DISABLED errors
- Specifically detects and guides users on API key restriction issues
- Provides direct links to Google Cloud Console for:
  - API enablement
  - API key restrictions
  - Billing settings
- Includes step-by-step troubleshooting guidance

**Example Error Message:**
```
Google Cloud Vision API is not enabled for project 842128635996.

Troubleshooting Steps:
1. Verify API is enabled: [link]
2. Check API key restrictions: [link]
   - Ensure 'Cloud Vision API' is in allowed APIs (if restrictions enabled)
3. Verify billing is active: [link]
4. Wait 5-10 minutes if you just enabled it (propagation delay)
```

### 2. Enhanced Diagnostics Dashboard

**File:** `v2/admin/ocr-diagnostics.php`

- Added comprehensive troubleshooting guide section for 403 errors
- Highlights API key restrictions as the most common issue
- Provides step-by-step instructions with visual formatting
- Dynamic project-specific links based on detected project number
- Quick action links updated to use detected project number

**Features:**
- Troubleshooting checklist with numbered steps
- Visual highlighting of common issues
- Direct links to Google Cloud Console
- Project-specific guidance

### 3. Enhanced Verification Scripts

**Files:**
- `v2/scripts/check-vision-api-enabled.php`
- `v2/scripts/verify-vision-api-status.php`

**Improvements:**
- Added API key restriction check as first troubleshooting step
- Comprehensive troubleshooting guidance in output
- Links to detailed documentation
- Clear prioritization of common issues

### 4. Comprehensive Documentation

**New File:** `docs/systems/ocr/API_KEY_RESTRICTIONS_TROUBLESHOOTING.md`

Complete guide covering:
- Common scenario explanation
- Step-by-step fix instructions
- Visual configuration examples
- Quick reference URLs
- Troubleshooting checklist

**Updated Files:**
- `docs/systems/ocr/GOOGLE_VISION_API_SETUP.md` - Added restriction troubleshooting link
- `docs/systems/ocr/IMPLEMENTATION_SUMMARY.md` - Updated with new troubleshooting features

## Common Issues Addressed

### Issue 1: API Key Restrictions (Most Common)

**Symptom:** Vision API shows as enabled, but calls return 403 SERVICE_DISABLED

**Root Cause:** API key has "API restrictions" enabled, but "Cloud Vision API" is not in the allowed APIs list

**Solution:** 
1. Go to API Credentials
2. Edit your API key
3. Check "API restrictions"
4. Ensure "Cloud Vision API" is in allowed APIs
5. Save and wait 1-2 minutes

### Issue 2: API Not Enabled

**Symptom:** 403 error with "has not been used" or "disabled" message

**Root Cause:** Vision API is not enabled for the project

**Solution:**
1. Go to API Library → Cloud Vision API
2. Click "Enable"
3. Wait 5-10 minutes for propagation

### Issue 3: Billing Not Active

**Symptom:** 403 error mentioning billing

**Root Cause:** Billing account not active or not linked to project

**Solution:**
1. Go to Billing settings
2. Verify billing account is "Active"
3. Verify project is linked to billing account

### Issue 4: Propagation Delay

**Symptom:** Just enabled API but still getting 403

**Root Cause:** Changes take 5-10 minutes to propagate

**Solution:** Wait 5-10 minutes and test again

## Testing

After implementing fixes, test with:

```bash
# Quick test
php v2/scripts/quick-vision-api-test.php

# Full verification
php v2/scripts/check-vision-api-enabled.php

# Status check
php v2/scripts/verify-vision-api-status.php

# Diagnostics dashboard
# Visit: /v2/admin/ocr-diagnostics.php?debug=1
```

## Related Documentation

- [API Key Restrictions Troubleshooting](API_KEY_RESTRICTIONS_TROUBLESHOOTING.md)
- [Vision API Setup Guide](GOOGLE_VISION_API_SETUP.md)
- [Implementation Summary](IMPLEMENTATION_SUMMARY.md)