Обработка ошибок в Love&Pay Crypto API

При работе с Love&Pay Crypto API могут возникать различные ошибки. В этом разделе описывается формат ошибок, типичные коды HTTP и их значения, а также рекомендации по повторным попыткам и идемпотентности.

Формат ошибки#

Ошибки в API возвращаются в формате JSON с описанием ошибки и дополнительной информацией. Пример ответа с ошибкой:

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The request is missing required parameters."
  },
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Поля ответа с ошибкой#

• success: Логическое значение, указывающее на успешность запроса. Для ошибок всегда false.
• error: Объект с информацией об ошибке.
  • code: Строковый код ошибки, который можно использовать для программной обработки.
  • message: Человеко-читаемое сообщение об ошибке.
• requestId: Уникальный идентификатор запроса, который можно использовать для отладки и поддержки.

Таблица кодов HTTP и их значений#

Типичные причины ошибок#

• 400 Bad Request: Отсутствуют обязательные параметры или они имеют неверный формат.
• 401 Unauthorized: Неверные данные авторизации.
• 403 Forbidden: Недостаточно прав для выполнения операции.
• 404 Not Found: Ресурс с указанным идентификатором не существует.
• 409 Conflict: Нарушение идемпотентности, например, повторный запрос с тем же externalId или X-Idempotency-Key.
• 429 Too Many Requests: Превышено количество запросов в единицу времени.
• 500 Internal Server Error: Проблемы на стороне сервера.

Рекомендации по повторным попыткам и идемпотентности#

Повторные попытки#

• Для ошибок 5xx (например, 500) рекомендуется повторить запрос через некоторое время.
• Для ошибок 429 (Too Many Requests) следует учитывать заголовок Retry-After, если он предоставлен.

Идемпотентность#

• Используйте externalId для идемпотентности при создании счетов через POST /api/v2/crypto/invoices.
• Используйте заголовок X-Idempotency-Key для идемпотентности при отправке выплат через POST /api/v2/crypto/payouts.
• Повторный запрос с тем же externalId или X-Idempotency-Key должен возвращать тот же результат, что и первоначальный запрос, если он был успешным.