Перейти к основному содержанию

Введение

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

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

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

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

Уведомление Обработано:
{
  "success": true,
  "message": "Уведомление успешно поставлено в очередь",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z"
}
Шаблоны Получены:
{
  "templates": [
    {
      "id": "template_001",
      "name": "welcome_user",
      "status": "approved"
    }
  ],
  "total": 1
}
Шаблон Создан:
{
  "success": true,
  "message": "Шаблон успешно создан",
  "template": {
    "id": "new_template_123",
    "name": "order_confirmation",
    "status": "pending"
  }
}

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

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

Отсутствует Обязательное Поле:
{
  "error": "validation_failed",
  "message": "Отсутствует обязательное поле",
  "details": {
    "field": "contact.number",
    "reason": "Это поле обязательно"
  },
  "request_id": "req_123456789"
}
Недопустимый Формат Параметра:
{
  "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 - Ошибка Аутентификации

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

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

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

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

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

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

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

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

Достигнут Лимит:
{
  "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

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

502 Bad Gateway

Ошибка Сервиса Upstream:
{
  "error": "service_unavailable",
  "message": "Сервис WhatsApp временно недоступен",
  "details": {
    "service": "whatsapp_gateway",
    "estimated_recovery": "2024-12-20T16:00:00Z"
  },
  "request_id": "req_123456804"
}

503 Service Unavailable

Режим Обслуживания:
{
  "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 при обращении в поддержку для более быстрого разрешения проблем.