Ошибки и лимиты

Формат ошибки

Любая ошибка — статус HTTP и один и тот же конверт:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ошибка валидации",
    "fields": {"return_url": "Нужен адрес https"}
  }
}

code — машиночитаемый код. Ветвитесь по нему, а не по статусу и не по тексту.
message — текст для логов на языке из Accept-Language. Клиенту его не показывайте: формулировки меняются.
fields — поле и причина у VALIDATION_ERROR; у остальных ошибок null.

Незнакомый code трактуйте как обычный отказ: список кодов пополняется без смены версии. Исключение — запрос на несуществующий путь или неподдерживаемый метод: он отвечает 404 или 405 с телом {"detail": …} без конверта. Это ошибка в адресе запроса, а не ответ API, — сверьте путь и метод со списком эндпоинтов.

Коды

Код	HTTP	Когда	Что делать
`UNAUTHORIZED`	401	Ключ неверный или отозван, доступ к API выключен или аккаунт партнёра заблокирован платформой	Сверить начало ключа в кабинете, раздел «API» — там же видно, выключен ли доступ; повтор не поможет
`VALIDATION_ERROR`	422	Тело или параметры не той формы — подробности в `fields`	Исправить запрос
`RATE_LIMITED`	429	Превышен лимит запросов	Повторить после паузы из `Retry-After`
`IDEMPOTENCY_KEY_REQUIRED`	400	Нет `Idempotency-Key` на `POST /payments`	Добавить ключ
`IDEMPOTENCY_KEY_TOO_LONG`	400	Ключ длиннее 200 символов	Короче ключ
`IDEMPOTENCY_KEY_REUSE`	409	Ключ уже занят счётом с другими полями. Счёт не выставлен	Новый ключ
`OPERATION_IN_PROGRESS`	409	Счёт по этому ключу ещё выставляется. Второй счёт не выставлен	Повторить тем же ключом через пару секунд
`PAYMENT_UNAVAILABLE`	503	Сервис оплаты не ответил. Счёт не выставлен	Повторить тем же ключом
`UNSUPPORTED_PAYMENT_METHOD`	400	Способ оплаты сейчас недоступен	Другой способ из `GET /payment-methods`
`PLAN_NOT_FOUND`	404	Тарифа нет или он снят с продажи	Перечитать `GET /plans`
`PAYMENT_NOT_FOUND`	404	Такого счёта в вашем аккаунте нет	—
`API_CLIENT_NOT_FOUND`	404	Такого клиента в вашем аккаунте нет	Клиент заводится счётом или пробным периодом
`API_CLIENT_BLOCKED`	403	Клиент заблокирован платформой	—
`NO_ACTIVE_SUBSCRIPTION`	400	Операции нужна действующая подписка (доп. устройства, перевыпуск ссылки)	Сначала продление
`DEVICE_SLOT_LIMIT_EXCEEDED`	400	Достигнут потолок устройств на клиента	—
`DEVICE_SLOTS_NOT_APPLICABLE`	400	У клиента устройства без ограничения. Счёт не выставлен	—
`DEVICES_NOT_FOR_SALE`	409	Доп. устройства сейчас не продаются	—
`DEVICE_NOT_FOUND`	404	Такого устройства у клиента нет	Перечитать `GET …/devices`
`TRIAL_DISABLED`	403	Пробный период вашему аккаунту выключен платформой	Написать менеджеру
`TRIAL_ALREADY_USED`	409	У клиента уже была подписка	—
`LINK_ROTATE_TOO_SOON`	429	Ссылку перевыпускали меньше часа назад	Повторить после паузы из `Retry-After`
`SERVICE_UNAVAILABLE`	503	VPN-сервис временно не ответил. Пробный период при этом не выдан	Повторить позже
`INTERNAL_ERROR`	500	Внутренняя ошибка	Повторить; на `POST /payments` — тем же ключом

«—» в последней колонке — повтор того же запроса ничего не изменит.

Что безопасно повторять

GET — всегда.
POST /payments — с тем же Idempotency-Key: второй счёт не выставится.
POST …/trial после 503 — пробный период не выдан, повтор безопасен.
POST …/rotate-link после 503 — ссылка не сменилась, пауза в час не началась.

Лимиты

Что	Лимит	Ответ при превышении
Все запросы аккаунта	600 в минуту	`429 RATE_LIMITED`, `Retry-After`
`POST /payments`	60 в минуту	`429 RATE_LIMITED`, `Retry-After`
Перевыпуск ссылки	раз в час на клиента	`429 LINK_ROTATE_TOO_SOON`, `Retry-After`

Retry-After — пауза в секундах. Лимиты защищают от зациклившегося скрипта; если для вашего объёма их мало — напишите менеджеру.

Версии

Версия — в пути: /api/partner/v1. Внутри версии добавляются новые поля в ответах, новые необязательные поля в запросах, новые коды ошибок и новые типы событий — код интеграции не должен на них ломаться: незнакомое поле пропускайте, незнакомый код ошибки трактуйте как обычный отказ, на незнакомое событие отвечайте 2xx. Удаление и переименование — только в новой версии пути (/v2).

Начало

Как это работает

Формат ошибки

Коды

Что безопасно повторять

Лимиты

Версии

​Формат ошибки

​Коды

​Что безопасно повторять

​Лимиты

​Версии

Формат ошибки

Коды

Что безопасно повторять

Лимиты

Версии