Коды ошибок

Этот документ перечисляет все error.code, которые возвращают публичные маршруты /v1 и /checkout/v1, с HTTP-статусом, который использует сервис, и тем, что делать клиенту. Прочитайте его, когда пишете обработку ошибок интеграции.

Тело ошибки

Любой ответ API с ошибкой имеет одно и то же тело:

{ "error": { "code": "route_not_found", "message": "Route not found" } }

Каждый ответ, включая ошибки, содержит заголовок X-Request-Id. Сообщайте его значение оператору, когда сообщаете о проблеме: по нему находится запрос в логах. Если клиент сам передал X-Request-Id из 1–128 латинских букв, цифр и символов ., _, :, -, сервис использует его, иначе генерирует UUID.

Описание OpenAPI, GET /v1/openapi.json, объявляет один список кодов для всех маршрутов сервиса, включая внутренние. Публичный маршрут возвращает только коды из перечня ниже.

Два вида ответов такого тела не имеют:

• HTTPS-прокси отвечает на путь вне /v1/ кодом 404 с пустым телом;
• во время остановки API отвечает 503 с телом в другом формате.

Ответ, тело которого не в формате выше, обрабатывайте по HTTP-статусу.

Как обрабатывать ошибки

• 400, 413, 415 — запрос неверный. Исправьте его: тот же запрос получит ту же ошибку.
• 401 — проверьте ключ и имя заголовка.
• 403 — мерчант отключён или не одобрен. Запросы будут отклоняться, пока это не изменит владелец или оператор.
• 404 — проверьте путь и идентификатор.
• 409 — запрос конфликтует с существующим объектом: ключ идемпотентности (order_id, reference) использован повторно с другими данными, или выбор токена на странице оплаты уже сделан либо уже невозможен. Не повторяйте тот же запрос.
• 422 — запрос корректен, но его отклоняет бизнес-правило; код называет правило. Тот же запрос получит ту же ошибку, пока не изменится настройка, стоящая за правилом.
• 429 — повторите через число секунд из заголовка retry-after.
• 500, 503 — проблема сервиса. Повторите позже с растущей задержкой и тем же ключом идемпотентности: order_id для инвойса, reference для выплаты. Повтор не создаёт второй объект.
• Кода нет в перечне — обработайте ответ по классу HTTP-статуса: 4xx — ошибка в запросе, 5xx — проблема сервиса.

Перечень

Примеры

Несуществующий путь:

curl -s https://api.stons.io/v1/unknown

404:

{"error":{"code":"route_not_found","message":"Route not found"}}

Запрос к POST /v1/invoices с "expires_in": 60 не проходит проверку по схеме, и details перечисляет все проблемные поля:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": [{ "path": "body.expires_in", "message": "Too small: expected number to be >=300" }]
  }
}

Запрос с "asset": "USDT_TRON" и "amount": "49.9000001" проходит проверку по схеме, но не проходит проверку числа знаков, поэтому details нет:

{
  "error": {
    "code": "validation_failed",
    "message": "amount: amount has more than 6 digits after the decimal point (USDT_TRON has 6 decimals)"
  }
}