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

Руководство по обработке ошибок при интеграции с 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 бонусов:

  • Проводите операцию без бонусов

  • Сохраняйте данные для повторной обработки

  • Информируйте пользователя о временной недоступности