GGWPAY docs

Ошибки #

Один конверт на все ручки.

json
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "amount_minor must be > 0",
    "request_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
  }
}
ПолеТипОписание
codestringМашиночитаемый код. Ветвите логику по нему
messagestringТекст для лога. Может измениться в любой момент
detailsobjectНеобязательные подробности, зависят от ошибки
request_idstringЕсть, только если вы прислали X-Request-Id. Идентификатор запроса всегда возвращается в заголовке ответа X-Request-Id — его и прикладывайте к обращению в поддержку

Коды #

КодHTTPКогдаЧто делать
INVALID_ARGUMENT400Данные не прошли проверку: пустое обязательное поле, неизвестное поле в теле, сумма ≤ 0, реквизит не по способу, недостаточно средств на выводеИсправьте запрос. Повтор без изменений даст то же самое
UNAUTHORIZED401Нет Authorization, ключ не найден, секрет не совпал, прислан один заголовок подписи из двух, подпись неверна, метка времени вне окна ±5 минПроверьте ключ и подпись, синхронизируйте часы по NTP
PAYMENT_DECLINED402Зарезервировано, ни одна ручка сегодня его не возвращаетОбработку не пишите
FORBIDDEN403Ключ действителен, но без нужного права (p2p:payin / p2p:payout) — в том числе вывод (settlement) ключом «только приём», или у ключа не задано ни одного права. Таблица прав — в «Авторизации»Тем же ключом не повторять, нужен ключ с правом
NOT_FOUND404Объекта нет или он чужой — случаи намеренно неразличимы. Тот же код — для пути, которого у API нетПроверьте reference и путь. Уверены, что ваш — в поддержку
STORE_RATE_NOT_SET422Запрос верный, но у магазина вашего ключа площадка ещё не назначила ставку по этому способу и направлению (details: store_id, payment_method, direction). Заявка не создана. Явно назначенные 0 % — это ставка, она проходитПовтор без изменений даст то же самое — напишите в поддержку, ставку назначит площадка; после этого запрос пройдёт
METHOD_NOT_ALLOWED405Путь настоящий, метод не тот (например, HEAD). В заголовке Allow — допустимые методыИспользуйте метод из Allow
CONFLICT409Запрос противоречит состоянию: спор уже открыт, окно спора истекло, адрес вывода не ACTIVEПеречитайте текущее состояние прежде, чем повторять
IDEMPOTENCY_CONFLICT409Тот же merchant_reference с другими деньгами — см. нижеНовый заказ — новый merchant_reference
REQUEST_TOO_LARGE413Тело больше 1 МиБ (в песочнице — больше 4 КиБ)Проверьте metadata — туда обычно попадает лишнее
RATE_LIMITED429Превышен лимит: ~20 запросов/с с всплеском до 40, считается на мерчанта, а не на IP (песочница — на IP)Заголовок Retry-After (секунды), затем повтор. Не наращивайте опрос — используйте коллбек
RATE_LIMITED429Слишком много неверных ключей с вашего адреса (неизвестный ключ или неверный секрет; IPv6 считается по подсети /64). Верные ключи этот лимит не затрагиваетRetry-After, затем повтор. Проверьте, что в запросе именно действующий ключ: подбор и опечатки в цикле блокируют адрес
INTERNAL500Ошибка на нашей сторонеПовтор с выдержкой. Запрос с merchant_reference безопасно повторить один в один
UNAVAILABLE503Часть платформы временно недоступна. В том числе «проверка ключа занята: повторите запрос» — все места проверки ключей заняты дольше 1,5 с; приходит с Retry-After: 1Повтор с экспоненциальной выдержкой

Повторять: 429, 503, 500, сетевые таймауты — с экспоненциальной выдержкой и джиттером. Не повторять: 400, 401, 403, 404, 409; 422 STORE_RATE_NOT_SET — только после того, как площадка назначит ставку.

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

merchant_reference в POST /gw/v1/collect, POST /gw/v1/disburse и POST /gw/v1/settlement — ключ идемпотентности. Повтор возвращает уже созданный объект с кодом 200 вместо 201.

РучкаСверяемые поляРасхождение
/gw/v1/collect, /gw/v1/disburseнаправление, amount_minor, currency, method409 IDEMPOTENCY_CONFLICT, ничего не создаётся и не меняется
/gw/v1/settlementвид вывода, amount_minor, валюта, chain_id, payout_address_idТо же

Остальные поля (metadata, recipient) не сверяются: при расхождении молча возвращается первый объект, новые значения игнорируются. То есть опечатку в реквизите получателя идемпотентность за вас не поймает — генерируйте merchant_reference так, чтобы он не мог повториться для двух разных заказов.