solver-sdk/docs/ERROR_HANDLING.md

SDK для интеграции с Code Solver Backend API (совместимо с браузером и Node.js), с поддержкой функциональности мышления (Thinking Mode)

# Обработка ошибок в Solver SDK

Документация по системе обработки ошибок в Solver SDK, включая общие ошибки, ошибки WebSocket и географические ограничения.

## Содержание

- [Общие принципы](#общие-принципы)
- [Типы ошибок](#типы-ошибок)
- [HTTP ошибки](#http-ошибки)
- [WebSocket ошибки](#websocket-ошибки)
- [Ошибки географических ограничений](#ошибки-географических-ограничений)
- [Примеры обработки ошибок](#примеры-обработки-ошибок)

## Общие принципы

Solver SDK использует следующие принципы при работе с ошибками:

1. **Унифицированный формат** — все ошибки имеют единую структуру
2. **Информативные сообщения** — ошибки содержат детальное описание проблемы
3. **Коды ошибок** — каждая ошибка имеет уникальный код для идентификации
4. **Типизация** — ошибки классифицируются по типам для удобной обработки

## Типы ошибок

Основные типы ошибок в SDK:

| Тип ошибки | Описание |
|------------|----------|
| `http_error` | Ошибки HTTP запросов |
| `websocket_error` | Ошибки WebSocket соединений |
| `validation_error` | Ошибки валидации входных данных |
| `authentication_error` | Ошибки аутентификации |
| `rate_limit_error` | Ошибки превышения лимита запросов |
| `provider_error` | Ошибки провайдеров API (Anthropic, OpenAI) |
| `geo_restriction` | Ошибки географических ограничений |

## HTTP ошибки

HTTP ошибки возникают при проблемах с HTTP запросами:

```javascript
try {
  const result = await sdk.chat.chat([{ role: 'user', content: 'Hello' }]);
} catch (error) {
  console.error(`Код ошибки: ${error.code}`);
  console.error(`Сообщение: ${error.message}`);
  
  // Проверка типа ошибки
  if (error.code === 401) {
    console.error('Ошибка аутентификации: проверьте API ключ');
  } else if (error.code === 429) {
    console.error('Превышен лимит запросов: повторите позже');
  }
}
```

## WebSocket ошибки

WebSocket ошибки обрабатываются через обработчики событий:

```javascript
const handleEvent = (eventType, data) => {
  if (eventType === 'error') {
    console.error(`WebSocket ошибка: ${data.message} (код: ${data.code})`);
    
    // Обработка конкретных типов ошибок
    switch (data.type) {
      case 'connection_error':
        console.error('Проблема с подключением, пробуем переподключиться...');
        break;
      case 'authentication_error':
        console.error('Проблема аутентификации, запрашиваем новый токен...');
        break;
      case 'timeout_error':
        console.error('Превышен таймаут ожидания ответа');
        break;
    }
  }
};

// Передаем обработчик событий
await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
```

## Ошибки географических ограничений

> **Добавлено в версии 1.7.4**

Начиная с версии 1.7.4 SDK поддерживает специальную обработку ошибок географических ограничений API Anthropic. Эти ошибки возникают, когда запросы отправляются из регионов, не поддерживаемых API Anthropic:

```javascript
try {
  const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
} catch (error) {
  // Проверка наличия ошибки географических ограничений
  if (error.type === 'geo_restriction') {
    console.error('==============================================');
    console.error('⚠️  ОШИБКА ГЕОГРАФИЧЕСКОГО ОГРАНИЧЕНИЯ API ANTHROPIC');
    console.error('⚠️  Для работы с API Anthropic требуется VPN или прокси');
    console.error('⚠️  Anthropic API доступен только из определенных регионов');
    console.error('==============================================');
    
    // Возможные действия:
    // 1. Предложить пользователю включить VPN
    // 2. Переключиться на другой провайдер API
    // 3. Использовать прокси-сервер
  }
}
```

Через обработчик WebSocket событий:

```javascript
const handleEvent = (eventType, data) => {
  if (eventType === 'error' && data.type === 'geo_restriction') {
    console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
    
    // Выполнить действия по настройке VPN или показать инструкции пользователю
  }
};
```

### Причины ошибок географических ограничений

Основные причины возникновения ошибок географических ограничений:

1. **Региональные ограничения API Anthropic** — API доступен только из определенных регионов (США, Европа и некоторые другие)
2. **Регуляторные требования** — законодательство некоторых стран ограничивает доступ к определенным API
3. **IP-блокировка** — некоторые IP-адреса могут быть заблокированы провайдером API

### Решение проблемы

Для решения проблемы географических ограничений:

1. **Использование VPN** — подключитесь через VPN к поддерживаемому региону (США, Европа)
2. **Прокси-сервер** — настройте прокси для запросов к API
3. **Альтернативные провайдеры** — используйте альтернативных провайдеров, доступных в вашем регионе

## Примеры обработки ошибок

### Комплексная обработка ошибок

```javascript
async function exampleWithErrorHandling() {
  const sdk = new CodeSolverSDK({
    baseURL: 'https://api.example.com',
    apiKey: 'your-api-key'
  });
  
  const messages = [
    { role: 'user', content: 'Explain quantum computing' }
  ];
  
  const options = {
    model: 'claude-3-7-sonnet-20240229',
    thinking: true,
    authToken: 'your-auth-token'
  };
  
  // Обработчик WebSocket событий
  const handleEvent = (eventType, data) => {
    // Обработка ошибок
    if (eventType === 'error') {
      console.error(`Ошибка: ${data.message}`);
      
      // Проверка типа ошибки
      switch (data.type) {
        case 'geo_restriction':
          console.error('Географическое ограничение: требуется VPN');
          break;
        case 'authentication_error':
          console.error('Ошибка аутентификации: неверный токен');
          break;
        case 'rate_limit_error':
          console.error('Превышен лимит запросов');
          break;
        default:
          console.error(`Неизвестная ошибка типа: ${data.type}`);
          break;
      }
    }
  };
  
  try {
    const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
    console.log(`Успешно отправлен запрос, Socket ID: ${response.socketId}`);
  } catch (error) {
    console.error(`Критическая ошибка: ${error.message}`);
    
    // Обработка специфических типов ошибок
    if (error.type === 'geo_restriction') {
      showVpnInstructions(); // Показать инструкции по настройке VPN
    } else if (error.status === 429) {
      scheduleRetry(5000); // Запланировать повторную попытку через 5 секунд
    } else {
      reportError(error); // Отправить отчет об ошибке
    }
  }
}
```

### Обработка ошибок при работе с рассуждениями

```javascript
try {
  // Создание рассуждения
  const reasoning = await sdk.reasoning.createReasoning({
    projectId: 'project-123',
    query: 'Analyze this codebase'
  });
  
  // Подключение WebSocket
  await sdk.reasoning.connectWebSocket({
    reasoningId: reasoning.id,
    authToken: 'your-auth-token',
    onError: (error) => {
      console.error(`WebSocket ошибка: ${error.message}`);
      
      if (error.type === 'geo_restriction') {
        // Показать сообщение о необходимости VPN
        showVpnAlert();
      }
    }
  });
  
  // Запуск рассуждения
  await sdk.reasoning.startReasoning(reasoning.id);
} catch (error) {
  console.error(`HTTP ошибка: ${error.message}`);
  
  // Обработка HTTP ошибок
  if (error.status === 401) {
    // Перенаправить на страницу входа
    redirectToLogin();
  } else if (error.status === 403) {
    // Показать сообщение об отсутствии доступа
    showAccessDeniedMessage();
  }
}
```