Ошибки #
Один конверт на все ручки.
json
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "amount_minor must be > 0",
"request_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}
}| Поле | Тип | Описание |
|---|---|---|
code | string | Машиночитаемый код. Ветвите логику по нему |
message | string | Текст для лога. Может измениться в любой момент |
details | object | Необязательные подробности, зависят от ошибки |
request_id | string | Есть, только если вы прислали X-Request-Id. Идентификатор запроса всегда возвращается в заголовке ответа X-Request-Id — его и прикладывайте к обращению в поддержку |
Коды #
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
INVALID_ARGUMENT | 400 | Данные не прошли проверку: пустое обязательное поле, неизвестное поле в теле, сумма ≤ 0, реквизит не по способу, недостаточно средств на выводе | Исправьте запрос. Повтор без изменений даст то же самое |
UNAUTHORIZED | 401 | Нет Authorization, ключ не найден, секрет не совпал, прислан один заголовок подписи из двух, подпись неверна, метка времени вне окна ±5 мин | Проверьте ключ и подпись, синхронизируйте часы по NTP |
PAYMENT_DECLINED | 402 | Зарезервировано, ни одна ручка сегодня его не возвращает | Обработку не пишите |
FORBIDDEN | 403 | Ключ действителен, но без нужного права (p2p:payin / p2p:payout) — в том числе вывод (settlement) ключом «только приём», или у ключа не задано ни одного права. Таблица прав — в «Авторизации» | Тем же ключом не повторять, нужен ключ с правом |
NOT_FOUND | 404 | Объекта нет или он чужой — случаи намеренно неразличимы. Тот же код — для пути, которого у API нет | Проверьте reference и путь. Уверены, что ваш — в поддержку |
STORE_RATE_NOT_SET | 422 | Запрос верный, но у магазина вашего ключа площадка ещё не назначила ставку по этому способу и направлению (details: store_id, payment_method, direction). Заявка не создана. Явно назначенные 0 % — это ставка, она проходит | Повтор без изменений даст то же самое — напишите в поддержку, ставку назначит площадка; после этого запрос пройдёт |
METHOD_NOT_ALLOWED | 405 | Путь настоящий, метод не тот (например, HEAD). В заголовке Allow — допустимые методы | Используйте метод из Allow |
CONFLICT | 409 | Запрос противоречит состоянию: спор уже открыт, окно спора истекло, адрес вывода не ACTIVE | Перечитайте текущее состояние прежде, чем повторять |
IDEMPOTENCY_CONFLICT | 409 | Тот же merchant_reference с другими деньгами — см. ниже | Новый заказ — новый merchant_reference |
REQUEST_TOO_LARGE | 413 | Тело больше 1 МиБ (в песочнице — больше 4 КиБ) | Проверьте metadata — туда обычно попадает лишнее |
RATE_LIMITED | 429 | Превышен лимит: ~20 запросов/с с всплеском до 40, считается на мерчанта, а не на IP (песочница — на IP) | Заголовок Retry-After (секунды), затем повтор. Не наращивайте опрос — используйте коллбек |
RATE_LIMITED | 429 | Слишком много неверных ключей с вашего адреса (неизвестный ключ или неверный секрет; IPv6 считается по подсети /64). Верные ключи этот лимит не затрагивает | Retry-After, затем повтор. Проверьте, что в запросе именно действующий ключ: подбор и опечатки в цикле блокируют адрес |
INTERNAL | 500 | Ошибка на нашей стороне | Повтор с выдержкой. Запрос с merchant_reference безопасно повторить один в один |
UNAVAILABLE | 503 | Часть платформы временно недоступна. В том числе «проверка ключа занята: повторите запрос» — все места проверки ключей заняты дольше 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, method | 409 IDEMPOTENCY_CONFLICT, ничего не создаётся и не меняется |
/gw/v1/settlement | вид вывода, amount_minor, валюта, chain_id, payout_address_id | То же |
Остальные поля (metadata, recipient) не сверяются: при расхождении молча возвращается первый объект, новые значения игнорируются. То есть опечатку в реквизите получателя идемпотентность за вас не поймает — генерируйте merchant_reference так, чтобы он не мог повториться для двух разных заказов.