# Network Error Detection

## Overview

This implementation adds intelligent network error detection to the Banatie API service. It follows best practices by **only checking connectivity when errors occur** (zero overhead on successful requests) and provides clear, actionable error messages to users.

## Features

### ✅ Lazy Validation
- Network checks **only trigger on failures**
- Zero performance overhead on successful requests
- Follows the fail-fast pattern

### ✅ Error Classification
Automatically detects and classifies:
- **DNS Resolution Failures** (`ENOTFOUND`, `EAI_AGAIN`)
- **Connection Timeouts** (`ETIMEDOUT`)
- **Connection Refused** (`ECONNREFUSED`)
- **Connection Resets** (`ECONNRESET`, `ENETUNREACH`)
- **Generic Network Errors** (fetch failed, etc.)

### ✅ Clear User Messages

**Before:**
```
Gemini AI generation failed: exception TypeError: fetch failed sending request
```

**After:**
```
Network error: Unable to connect to Gemini API. Please check your internet connection and firewall settings.
```

### ✅ Detailed Logging

Logs contain both user-friendly messages and technical details:
```
[NETWORK ERROR - DNS] DNS resolution failed: Unable to resolve Gemini API hostname | Technical: Error code: ENOTFOUND
```

## Implementation

### Core Utility

**Location:** `src/utils/NetworkErrorDetector.ts`

**Key Methods:**
- `classifyError(error, serviceName)` - Analyzes an error and determines if it's network-related
- `formatErrorForLogging(result)` - Formats errors for logging with technical details

### Integration Points

1. **ImageGenService** (`src/services/ImageGenService.ts`)
   - Enhanced error handling in `generateImageWithAI()` method
   - Provides clear network diagnostics when image generation fails

2. **PromptEnhancementService** (`src/services/promptEnhancement/PromptEnhancementService.ts`)
   - Enhanced error handling in `enhancePrompt()` method
   - Helps users diagnose connectivity issues during prompt enhancement

## How It Works

### Normal Operation (No Overhead)
```
User Request → Service → Gemini API → Success ✓
```
No network checks performed - zero overhead.

### Error Scenario (Smart Detection)
```
User Request → Service → Gemini API → Error ✗
              ↓
    NetworkErrorDetector.classifyError()
              ↓
    1. Check error code/message for network patterns
    2. If network-related: Quick DNS check (2s timeout)
    3. Return classification + user-friendly message
```

## Error Types

| Error Type | Trigger | User Message |
|-----------|---------|--------------|
| `dns` | ENOTFOUND, EAI_AGAIN | DNS resolution failed: Unable to resolve Gemini API hostname |
| `timeout` | ETIMEDOUT | Connection timeout: Gemini API did not respond in time |
| `refused` | ECONNREFUSED | Connection refused: Service may be down or blocked by firewall |
| `reset` | ECONNRESET, ENETUNREACH | Connection lost: Network connection was interrupted |
| `connection` | General connectivity failure | Network connection failed: Unable to reach Gemini API |
| `unknown` | Network keywords detected | Network error: Unable to connect to Gemini API |

## Testing

Run the manual test to see error detection in action:

```bash
npx tsx test-network-error-detector.ts
```

This demonstrates:
- DNS errors
- Timeout errors
- Fetch failures (actual error from your logs)
- Non-network errors (no false positives)

## Example Error Logs

### Before Implementation
```
[2025-10-09T16:56:29.228Z] [fmfnz0zp7] Text-to-image generation completed: {
  success: false,
  error: 'Gemini AI generation failed: exception TypeError: fetch failed sending request'
}
```

### After Implementation
```
[ImageGenService] [NETWORK ERROR - UNKNOWN] Network error: Unable to connect to Gemini API. Please check your internet connection and firewall settings. | Technical: exception TypeError: fetch failed sending request
```

## Benefits

1. **Better UX**: Users get actionable error messages
2. **Faster Debugging**: Developers immediately know if it's a network issue
3. **Zero Overhead**: No performance impact on successful requests
4. **Production-Ready**: Follows industry best practices (AWS SDK, Stripe, Google Cloud)
5. **Comprehensive**: Detects all major network error types

## Future Enhancements

Potential improvements:
- Retry logic with exponential backoff for transient network errors
- Circuit breaker pattern for repeated failures
- Metrics/alerting for network error rates
- Health check endpoint with connectivity status