Поиск по документации и руководствам

Предсказуемая обработка ошибок.

Создавайте идемпотентные повторы и решайте на сервере, когда повторять запрос.

HTTP-коды статуса

Код	Значение	Действие
201	Платёж создан или возвращён идемпотентный повтор	Читайте payment_url; details возвращает актуальный статус.
401	Данные доступа отсутствуют или неверны	Проверьте заголовок X-API-Key.
403	Создание приостановлено, бета ожидает активации / истекла или квота исчерпана	Проверьте limits и обратитесь в поддержку.
404	Платёж не найден	Проверьте ID платежа и аккаунт.
409	Незавершённый заказ на адресе; другой мерчант; нет вебхука; конфликт идемпотентности; отмена недоступна	Прочитайте detail и устраните конфликт состояния.
413	Тело запроса превышает 64 KiB	Уменьшите тело запроса.
422	Некорректные поля или адрес вебхука	Исправьте ошибки валидации.
429	Ограничение частоты запросов	Подождите и соблюдайте Retry-After, если он указан.
503	Инфраструктура временно недоступна	Повторяйте с увеличением задержки и тем же ключом идемпотентности.

Ответ ошибки

409 Conflict

{"detail":"Finish the current payment with this amount on this address first"}

Ошибки доступа только к созданию возвращают 403 с объектом в detail: code и message. Коды: beta_not_activated, beta_expired, creation_paused, total_quota_exhausted или daily_quota_exhausted; одновременная блокировка всего аккаунта может вернуть account_inactive. Перед повтором проверьте GET /api/v1/merchant/limits. Неактивные аккаунты обычно не проходят аутентификацию с 401. Сохранённый идемпотентный повтор в сроке хранения возвращает исходный ответ даже после истечения беты или квоты, но учитывается в техническом лимите частоты.

Ошибки валидации возвращают список в detail с некорректным полем и причиной. Не создавайте новый заказ в ответ на любую ошибку.

Доступ к созданию и квоты

Создание новых платежей может ограничиваться неактивированной / истёкшей бетой, паузой оператора, общей или суточной квотой UTC. Проверяйте состояние доступа и квоты создания через GET /api/v1/merchant/limits. Существующие платежи и вебхуки продолжают работу; технические лимиты частоты независимы.

Ограничения частоты по методам

Это настроенные стандартные значения. Счётчики приложения используют Redis и фиксированное окно 60 секунд с первого запроса. Следующие запросы не продлевают окно. Все API-ключи одного мерчанта делят лимиты.

Метод	Запросы / окно	Счётчик
`GET /api/v1/payments/{payment_id}/webhooks`	120 / 60 с	общие чтения · на мерчанта
`POST /api/v1/merchant/webhook/events/{event_id}/retry`	5 / 3600 с	ручной повтор · на мерчанта · 3600 секунд
`POST /api/v1/payments`	30 / 60 с	создание · на мерчанта
`POST /api/v1/payments/{payment_id}/cancel`	60 / 60 с	отмена · на мерчанта
`GET /api/v1/payments`	120 / 60 с	общие чтения · на мерчанта
`GET /api/v1/payments/page`	120 / 60 с	общие чтения · на мерчанта
`GET /api/v1/payments/{payment_id}/details`	120 / 60 с	общие чтения · на мерчанта
`GET /api/v1/merchant/limits`	120 / 60 с	общие чтения · на мерчанта
`GET /api/v1/merchant/webhook`	120 / 60 с	общие чтения · на мерчанта
`PUT /api/v1/merchant/webhook`	10 / 60 с	общие настройки вебхука · на мерчанта
`POST /api/v1/merchant/webhook/rotate-key`	10 / 60 с	общие настройки вебхука · на мерчанта
`POST /api/v1/merchant/rotate-key`	5 / 60 с	ротация API-ключа · на секрет ротации
`GET /api/v1/payments/{public_token}`	120 / 60 с	публичный статус · на токен платежа

Метод ручного повтора вебхука имеет отдельное окно 3600 секунд с первого запроса. Все методы чтения вместе допускают 120 запросов на мерчанта за окно, а не по 120 каждый. Обновление URL вебхука и ротация ключа подписи вместе допускают 10. Создание и отмена имеют отдельные счётчики. Ротация API-ключа не сбрасывает счётчики мерчанта. Идемпотентные повторы создания расходуют технический лимит частоты, хотя не расходуют квоту платежей. Прошедшие валидацию запросы учитываются, даже если дальнейшая обработка завершилась ошибкой; превышающие лимит попытки тоже учитываются, не продлевая окно. Ротация учитывается по переданному непустому секрету, включая неверные секреты.

Публичный статус имеет отдельный счётчик токена платежа, общий для всех посетителей. Видимая страница оплаты опрашивает статус каждые 3.8–4 секунды в PENDING или CHECKING (около 15 запросов в минуту на посетителя). Скрытые страницы приостанавливают опрос и обновляются сразу после появления. Сетевые ошибки увеличивают задержку до 30 секунд; событие online вызывает немедленную проверку.

Дополнительные лимиты nginx по IP клиента

Запросы к https://api.dedyx.com также проходят общие IP-лимиты публичного шлюза. nginx использует постоянную частоту с запасом всплеска, а не фиксированное окно приложения; разрешённые всплески проходят сразу.

Область	Постоянная частота	Запас всплеска
Все запросы /api/v1/ вместе	10 запросов / секунду	30; 10 для ротации API-ключа
Публичный статус платежа, дополнительно к IP-лимиту API	5 запросов / секунду	20
Ротация API-ключа, дополнительно к IP-лимиту API	1 запрос / минуту	3
Страницы и статические ресурсы	20 запросов / секунду	50
Одновременно активные запросы / соединения	30 на IP	—

Клиенты с одним публичным IP делят счётчики nginx, включая разных мерчантов и токены платежей. Любой из двух уровней может отклонить запрос с 429.

Обработка 429

Лимит приложения · пример

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{"detail":"Rate limit exceeded"}

Ответы приложения содержат Retry-After в секундах до конца окна. Подождите не меньше этого срока, добавьте случайную задержку и используйте исходные ключ и тело при повторе создания. Ответы nginx 429 сейчас не содержат Retry-After и могут быть HTML; проверяйте HTTP-статус до разбора JSON и используйте экспоненциальную задержку, если заголовка нет. При отказе ограничителя возвращается 503, а не разрешаются неограниченные запросы.

Восстановление после неопределённого ответа

Сохраняйте один ключ идемпотентности на логический заказ.
При потере ответа создания повторяйте с теми же телом и ключом.
До выполнения заказа читайте защищённый details платежа.
Атомарно исключайте повторные ID событий вебхука.