Обработка ошибок и рекомендации

Руководство по обработке ошибок при интеграции с API Sagi.

---

Коды ошибок HTTP

2xx - Успешные ответы

• 200 OK - Запрос выполнен успешно
• 201 Created - Ресурс создан (например, транзакция)

4xx - Ошибки клиента

• 400 Bad Request - Неверный формат данных или параметров
• 401 Unauthorized - Отсутствует или недействителен токен авторизации
• 403 Forbidden - Недостаточно прав доступа
• 404 Not Found - Ресурс не найден (например, пользователь)
• 429 Too Many Requests - Превышен лимит запросов

5xx - Ошибки сервера

• 500 Internal Server Error - Внутренняя ошибка сервера
• 502 Bad Gateway - Ошибка шлюза
• 503 Service Unavailable - Сервис временно недоступен
• 504 Gateway Timeout - Таймаут запроса

---

Специфичные коды ошибок Sagi

Пользователи и аутентификация (100-999)

Аутентификация

{
  "code": 401,
  "message": "authentication error"
}

{
  "code": 401,
  "message": "invalid login or password"
}

{
  "code": 401,
  "message": "invalid license"
}

{
  "code": 404,
  "message": "failed creating token"
}

Пользователи

{
  "code": 100,
  "message": "user not registered"
}

{
  "code": 403,
  "message": "wrong address identifier received"
}

{
  "code": 409,
  "message": "invalid gender provided"
}

{
  "code": 410,
  "message": "error format Birthday"
}

{
  "code": 411,
  "message": "user is not promoter"
}

{
  "code": 427,
  "message": "invalid length user code"
}

{
  "code": 428,
  "message": "can't find user by code"
}

Транзакции и заказы (3000-3999)

Доступ и права

{
  "code": 3000,
  "message": "denied access for provided order"
}

Суммы и лимиты

{
  "code": 3001,
  "message": "amount is less than minimum amount"
}

{
  "code": 3002,
  "message": "amount is greater than maximum amount"
}

{
  "code": 3006,
  "message": "invalid order amount"
}

Состояние заказов

{
  "code": 3013,
  "message": "invalid order state"
}

{
  "code": 3014,
  "message": "no such order in database"
}

{
  "code": 3015,
  "message": "order was manually reverted"
}

{
  "code": 3017,
  "message": "order already declined"
}

{
  "code": 3020,
  "message": "order time expired"
}

{
  "code": 3024,
  "message": "order is unable to revert"
}

Бонусы и баланс

{
  "code": 3023,
  "message": "user private balance is not enough"
}

{
  "code": 3025,
  "message": "code for using private balance is wrong"
}

Ошибки интеграции с Epay

{
  "code": 3010,
  "message": "epay integration error"
}

{
  "code": 3200,
  "message": "authorization error, invalid 3dsecure"
}

{
  "code": 3201,
  "message": "not permitted to client by his bank"
}

{
  "code": 3202,
  "message": "no such card"
}

{
  "code": 3203,
  "message": "not sufficient funds in his card"
}

{
  "code": 3204,
  "message": "card is expired"
}

{
  "code": 3206,
  "message": "exceeds withdrawal amount limit"
}

Филиалы (4000-4999)

Права доступа

{
  "code": 4000,
  "message": "no permission to create branch"
}

{
  "code": 4001,
  "message": "no permission to update branch"
}

{
  "code": 4033,
  "message": "no permission to view customers"
}

{
  "code": 4034,
  "message": "no permission to view transactions"
}

Конфигурация филиала

{
  "code": 4003,
  "message": "branch with specified id not found"
}

{
  "code": 4004,
  "message": "contract rules for branch were not specified"
}

{
  "code": 4051,
  "message": "branch is disabled"
}

{
  "code": 4064,
  "message": "private cashback is not activated for the branch"
}

Безопасность и черные списки

{
  "code": 4052,
  "message": "клиент в черном списке"
}

{
  "code": 4053,
  "message": "превышен лимит дневной транзакции"
}

Программы лояльности

{
  "code": 4037,
  "message": "the title of the award cannot be empty"
}

{
  "code": 4038,
  "message": "the stamp count of the award cannot be empty"
}

{
  "code": 4039,
  "message": "the number of awards received is less than the required number of awards"
}

Промокоды

{
  "code": 4057,
  "message": "промокод истек"
}

{
  "code": 4058,
  "message": "промокод уже был использован"
}

{
  "code": 4059,
  "message": "промокод не найден"
}

Телефоны и SMS (5000-5999)

{
  "code": 5000,
  "message": "invalid phone length"
}

{
  "code": 5002,
  "message": "not supported platform"
}

{
  "code": 5005,
  "message": "query is too short"
}

Общие ошибки (10000+)

{
  "code": 10000,
  "message": "no permission to this operation"
}

{
  "code": 10001,
  "message": "invalid uri path"
}

{
  "code": 10005,
  "message": "Неверные параметры"
}

{
  "code": 10006,
  "message": "Пользователя нет в черном списке"
}

---

Рекомендации по обработке ошибок

1. Повторные попытки

Повторять запрос только при временных ошибках: - HTTP 5xx (серверные ошибки) - HTTP 429 (превышен лимит запросов) - Сетевые таймауты

НЕ повторять при постоянных ошибках: - HTTP 4xx (ошибки клиента) - Коды ошибок связанные с бизнес-логикой (3xxx, 4xxx)

2. Логирование

Обязательно логируйте: - Все ошибки с кодами 3xxx и 4xxx - Повторные попытки запросов - Операции с финансами (бонусы, транзакции)

3. Пользовательские сообщения

Переводите коды ошибок в понятные сообщения: - 3025 → "Неверный код подтверждения"
- 4052 → "Клиент в черном списке филиала" - 3023 → "Недостаточно бонусов для списания" - 4051 → "Филиал временно недоступен"

4. Graceful degradation

При недоступности API бонусов: - Проводите операцию без бонусов - Сохраняйте данные для повторной обработки - Информируйте пользователя о временной недоступности