Формат ошибки
Любая ошибка возвращается с соответствующим 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_id4xx(кроме429) - повтор не поможет, исправьте запрос- Используйте экспоненциальную задержку между повторами