Формат ошибки
Любая ошибка возвращается с соответствующим HTTP-статусом и телом:
{"message": "Краткое описание ошибки."}
Коды
| Поле | Тип | Описание |
|---|---|---|
401опц. | Unauthorized | Отсутствует или неверный заголовок X-Api-Key. На подписанных маршрутах выплат сюда же относятся отсутствующий или просроченный X-Timestamp и отсутствующая или неверная X-Signature. |
403опц. | Forbidden | Мерчант отключён, не может принимать платежи, либо не задан callback_url. Также: IP не в списке разрешённых мерчанта, а на подписанных маршрутах — не настроен секрет мерчанта. |
404опц. | Not Found | Объект с указанным uuid или external_id не найден. |
409опц. | Conflict | Очень редкая гонка БД при одновременном создании с одинаковым external_id. В обычном случае повтор external_id идемпотентен — возвращается ранее созданный объект (HTTP 201), не ошибка. |
422опц. | Unprocessable Entity | Ошибка валидации тела запроса (см. поле errors), недопустимый callback_url, нехватка баланса для выплаты. При создании выплаты также: переданы запрещённые поля destination/metadata/callback_url. Ненайденный wallet_uuid возвращает 404, а не 422. |
429опц. | Too Many Requests | Превышен лимит запросов (rate limit) по ключу или IP. |
502опц. | Bad Gateway | Ошибка платёжного провайдера при инициации платежа или получении H2H-реквизитов. |
Обработка 429
При 429 Too Many Requests снизьте частоту и повторите запрос позже. Учитывайте заголовокRetry-After, если он присутствует. Лимиты считаются по API-ключу и по IP одновременно.
Повторные попытки
5xxи сетевые сбои — безопасно повторять с тем же external_id.4xx(кроме429) — повтор не поможет, исправьте запрос.- Используйте экспоненциальную задержку между повторами.