Ошибки

Каждый ответ 4xx/5xx несёт один и тот же JSON-конверт:

{
  "code": 400,
  "message": "invalid_input",
  "details": [
    { "field": "items[0].unit_price", "message": "must be a positive decimal string" }
  ]
}

• code — числовой HTTP-статус (400, 401, 404, …). Полезен для общей обработки на HTTP-уровне, но для логики ветвления переключайтесь по message — code не разделит, например, invalid_input и payment_method_not_supported (оба 400).
• message — sentinel-имя в нижнем snake_case, выведенное из внутренней константы errors.go (например, INVALID_INPUT → "invalid_input"). Стабильно между релизами — переключайтесь по нему.
• details — заполняется при ошибках валидации. Массив объектов { field, message }, чтобы клиент мог привязать ошибки к полям ввода. В остальных случаях не указывается.

{ "error": "unauthorized", "message": "invalid signature" }

HTTP-статус → типичные коды

Полный справочник кодов

Полный набор значений code, которые вы можете увидеть (совпадает с payment-service/pkg/errors/errors.go):

Аутентификация и сессии (401)

• INVALID_CREDENTIALS — комбинация username/password или API-ключа отклонена
• INVALID_TOKEN — JWT/сессионный токен непарсится или повреждён
• TOKEN_EXPIRED — JWT прошёл exp
• INVALID_OTP — OTP не совпал
• OTP_EXPIRED — OTP был выпущен раньше окна допуска
• SESSION_EXPIRED — сессия панели устарела
• INVALID_SIGNATURE — несовпадение HMAC-подписи на B2B / webhook-вызовах

Авторизация (403)

• FORBIDDEN — аутентифицирован, но роль/scope/граница мерчанта блокирует действие
• IP_BLOCKED — IP в списке злоупотреблений

Не найдено (404)

• NOT_FOUND — общая
• RECORD_NOT_FOUND — строка отсутствует по указанному ID
• USER_NOT_FOUND — пользователь не найден
• SESSION_NOT_FOUND — id сессии панели не распознан

Конфликт (409)

• ALREADY_EXISTS — общая
• USER_ALREADY_EXISTS — регистрация наткнулась на unique-constraint
• SESSION_ALREADY_EXISTS — дубль вставки сессии

Валидация (400)

• INVALID_INPUT — общая; смотрите details
• MISSING_REQUIRED — обязательное поле отсутствовало
• INVALID_FORMAT — значение не соответствовало ожидаемому формату (например, UUID, URL, email)
• INVALID_LENGTH — значение слишком короткое или слишком длинное
• INVALID_VALUE — значение вне допустимого enum/диапазона
• INVALID_USER_STATUS — пользователь в состоянии, запрещающем действие
• INVALID_USER_ROLE — у роли нет права на действие
• PAYMENT_METHOD_NOT_SUPPORTED — комбинация provider/asset не включена для мерчанта
• AMOUNT_BELOW_MINIMUM — сумма заказа ниже минимального порога (заданного на уровне сети или окружения). Поле details.floor_usd в ответе несёт настроенный порог (в USD), так что вы можете показать его напрямую; текст message тоже его называет.
• INSUFFICIENT_BALANCE — на кошельке покупателя недостаточно платёжного актива, чтобы покрыть перевод.
• INSUFFICIENT_GAS — на кошельке покупателя не хватает нативного газа, чтобы отправить перевод.

Платежи / биллинг (402)

• INSUFFICIENT_CREDIT — предоплаченный баланс мерчанта не покрывает gas / платформенную комиссию. Пополните через панель и повторите

Rate-limit (429)

• TOO_MANY_REQUESTS — rate-limit по IP на gateway
• TOO_MANY_ATTEMPTS — повторные неудачные попытки на одном ресурсе (например, OTP) сработали как троттл

Хранилище / инфраструктура (500)

• DATABASE_CONNECTION_ERROR — не удалось достучаться до БД
• DATABASE_QUERY_ERROR — план запроса упал на исполнении
• DATABASE_TRANSACTION_ERROR — commit/rollback не удался
• REDIS_CONNECTION_ERROR — не удалось достучаться до Redis
• REDIS_OPERATION_ERROR — команда Redis не удалась
• EXTERNAL_SERVICE_ERROR — общий сбой стороннего сервиса (provider не выделен отдельно ниже)
• TWILIO_SERVICE_ERROR — вызов Twilio SMS / Verify не удался
• SENDGRID_SERVICE_ERROR — отправка письма через SendGrid не удалась
• INTERNAL_SERVER_ERROR — неожиданный fall-through; снимите заголовок Date ответа и X-RateLimit-* и обратитесь

Доступность (503)

• SERVICE_UNAVAILABLE — критичный downstream сообщает о нездоровом состоянии; отступ + повтор

Ошибки валидации (400)

Когда проблема в некорректном теле запроса, details — это массив, чтобы вы могли сопоставить ошибки с полями:

{
  "code": 400,
  "message": "invalid_input",
  "details": [
    { "field": "items[0].unit_price", "message": "must be a positive decimal string" },
    { "field": "success_url", "message": "must be a valid https URL" }
  ]
}

Ошибки аутентификации (401)

INVALID_SIGNATURE покрывает три разных режима отказа — отличить их можно только методом исключения:

• Неправильный secret-ключ (перепроверьте env var)
• Расхождение по времени > 5 мин (синхронизируйте NTP)
• Неправильная каноническая строка (чаще всего: забыли \n-разделители или подписали распарсенное-и-пересериализованное тело, отличающееся от отправленного)

См. Аутентификация для точного алгоритма подписи.

Rate-limit’ы (429)

X-RateLimit-Limit и X-RateLimit-Remaining отправляются на каждом rate-limited ответе gateway (не только на успешных). Считайте их живым бюджетом для вашего IP.

Rate-limited ответы содержат заголовок Retry-After (секунды до сброса окна) — учитывайте его. В качестве fallback отступайте с jitter — 1с базы + экспонента до 30с.

Недостаточный кредит (402)

INSUFFICIENT_CREDIT (HTTP 402 Payment Required) означает, что предоплаченный баланс мерчанта не покрывает следующую комиссию gas и платформы для операции, которую вы пытались выполнить — обычно расчёт крипто-платежа или выполнение gas-спонсируемого on-chain действия. Пополните из панели мерчанта (Billing → Add credit) и повторите операцию; работа в полёте подождёт и автоматически продолжится, как только баланс восстановится.

Серверные ошибки (5xx)

500 означает, что мы не смогли обработать запрос. Повторите с отступом — ваш idempotency_key гарантирует, что вы не получите двойное списание, если оригинальный запрос частично выполнился.

Если повторы не восстанавливаются в течение минуты, покажите покупателю обобщённое «Платёж временно недоступен» и обратитесь в поддержку с проблемным endpoint’ом, вашим merchant ID, заголовком Date ответа и значениями X-RateLimit-*, а также приблизительным временем запроса — этого достаточно, чтобы мы нашли соответствующий запрос в наших логах.

Ошибки доставки webhook

Доставки webhook — отдельный канал отказов — они не всплывают как ошибки API, потому что вызывает не ваш сервер. Когда доставка возвращает non-2xx (или истекает по времени), она ставится в очередь повторов с экспоненциальным отступом 0с, 1мин, 5мин, 15мин, 1ч, 6ч (всего шесть попыток — то же расписание, что и на Webhooks → Обзор). Полная история по каждой доставке доступна в Developers → Webhooks → [endpoint] → Delivery log в панели. После шестой попытки доставка переходит в dead-letter — панель показывает бейдж «Failed», который можно вручную проиграть заново, когда ваш сервер восстановится.