> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Обработка Ошибок и Коды Ответов

> Комплексное руководство по обработке ошибок API и кодам ответов

## Введение

Это руководство охватывает все возможные коды ответов, форматы ошибок и лучшие практики обработки ошибок при интеграции с API Lovi.

## 📊 HTTP-Коды Статуса

### Успешные Ответы

#### 200 OK - Запрос Успешен

**Уведомление Обработано:**

```json theme={null}
{
  "success": true,
  "message": "Уведомление успешно поставлено в очередь",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z"
}
```

**Шаблоны Получены:**

```json theme={null}
{
  "templates": [
    {
      "id": "template_001",
      "name": "welcome_user",
      "status": "approved"
    }
  ],
  "total": 1
}
```

**Шаблон Создан:**

```json theme={null}
{
  "success": true,
  "message": "Шаблон успешно создан",
  "template": {
    "id": "new_template_123",
    "name": "order_confirmation",
    "status": "pending"
  }
}
```

***

### Ответы Ошибок Клиента (4xx)

#### 400 Bad Request - Недопустимые Параметры

**Отсутствует Обязательное Поле:**

```json theme={null}
{
  "error": "validation_failed",
  "message": "Отсутствует обязательное поле",
  "details": {
    "field": "contact.number",
    "reason": "Это поле обязательно"
  },
  "request_id": "req_123456789"
}
```

**Недопустимый Формат Параметра:**

```json theme={null}
{
  "error": "validation_failed",
  "message": "Недопустимый формат параметра",
  "details": {
    "field": "datetime_sending",
    "provided": "25-12-2024",
    "expected_format": "ISO 8601 (YYYY-MM-DDTHH:MM:SS)",
    "example": "2024-12-25T10:30:00"
  },
  "request_id": "req_123456790"
}
```

#### 401 Unauthorized - Ошибка Аутентификации

**Недопустимый Ключ Доступа:**

```json theme={null}
{
  "error": "unauthorized",
  "message": "Недопустимый или истекший ключ доступа",
  "details": {
    "reason": "Предоставленный access_key недопустим или был отозван"
  },
  "request_id": "req_123456793"
}
```

#### 403 Forbidden - Доступ Запрещен

**Недостаточные Разрешения:**

```json theme={null}
{
  "error": "forbidden",
  "message": "Недостаточные разрешения для этого ресурса",
  "details": {
    "reason": "Ваш API-ключ не имеет разрешения на создание шаблонов"
  },
  "request_id": "req_123456795"
}
```

#### 404 Not Found - Ресурс Не Найден

**Шаблон Не Найден:**

```json theme={null}
{
  "error": "template_not_found",
  "message": "Шаблон 'welcome_user' не найден или не утвержден",
  "details": {
    "template_name": "welcome_user",
    "language": "ru_RU",
    "suggestion": "Проверьте имя шаблона и статус утверждения"
  },
  "request_id": "req_123456797"
}
```

#### 422 Unprocessable Entity - Ошибка Логики Бизнеса

**Шаблон Не Утвержден:**

```json theme={null}
{
  "error": "template_not_approved",
  "message": "Шаблон не в утвержденном статусе",
  "details": {
    "template_name": "pending_template",
    "current_status": "pending",
    "required_status": "approved"
  },
  "request_id": "req_123456799"
}
```

#### 429 Too Many Requests - Превышен Лимит Скорости

**Достигнут Лимит:**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Слишком много запросов. Повторите попытку через 60 секунд",
  "details": {
    "limit": 100,
    "window": "1 час",
    "reset_time": "2024-12-20T16:30:00Z"
  },
  "retry_after": 60,
  "request_id": "req_123456801"
}
```

***

### Ответы Ошибок Сервера (5xx)

#### 500 Internal Server Error

**Общая Ошибка Сервера:**

```json theme={null}
{
  "error": "internal_error",
  "message": "Произошла непредвиденная ошибка",
  "details": {
    "reason": "Внутренняя ошибка сервера"
  },
  "request_id": "req_123456803"
}
```

#### 502 Bad Gateway

**Ошибка Сервиса Upstream:**

```json theme={null}
{
  "error": "service_unavailable",
  "message": "Сервис WhatsApp временно недоступен",
  "details": {
    "service": "whatsapp_gateway",
    "estimated_recovery": "2024-12-20T16:00:00Z"
  },
  "request_id": "req_123456804"
}
```

#### 503 Service Unavailable

**Режим Обслуживания:**

```json theme={null}
{
  "error": "service_unavailable",
  "message": "Сервис временно недоступен для обслуживания",
  "details": {
    "maintenance_window": "2024-12-20T02:00:00Z to 2024-12-20T04:00:00Z"
  },
  "request_id": "req_123456805"
}
```

***

## 🔄 Стратегии Повтора

### Рекомендуемая Логика Повтора

| Код Статуса     | Действие                                      | Стратегия Повтора                    |
| --------------- | --------------------------------------------- | ------------------------------------ |
| `400, 404, 422` | ❌ **Не повторять**                            | Исправить запрос и попробовать снова |
| `401, 403`      | ❌ **Не повторять**                            | Обновить аутентификацию              |
| `429`           | ⏰ **Повторить с задержкой**                   | Использовать заголовок `retry_after` |
| `500, 502, 503` | 🔄 **Повторить с экспоненциальной задержкой** | Макс 3 попытки                       |

***

## 📝 Лучшие Практики

### Чек-лист Обработки Ошибок

✅ **Валидация Перед Запросом**

* Валидировать формат номера телефона
* Проверять обязательные поля
* Валидировать формат даты/времени
* Проверять существование шаблона

✅ **Мониторинг Запросов**

* Логировать все API-запросы
* Включать request\_id в логи
* Мониторить время ответа
* Отслеживать частоту ошибок

✅ **Восстановление Ошибок**

* Реализовать соответствующую логику повтора
* Кешировать токены аутентификации
* Элегантно обрабатывать ограничения скорости
* Предоставлять значимые сообщения об ошибках пользователям

✅ **Пользовательский Опыт**

* Показывать понятные сообщения об ошибках
* Предоставлять полезную обратную связь
* Не раскрывать внутренние детали ошибок
* Предлагать альтернативы при возможности

Помните, всегда включать `request_id` при обращении в поддержку для более быстрого разрешения проблем.