> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vargopartners.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Коды ошибок, что делать с каждым, лимиты запросов и версии

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

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

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

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

Незнакомый `code` трактуйте как обычный отказ: список кодов пополняется без смены версии.

## Коды

| Код | HTTP | Когда | Что делать |
| - | - | - | - |
| `UNAUTHORIZED` | 401 | Ключ неверный или отозван, доступ к API выключен | Проверить ключ; повтор не поможет |
| `VALIDATION_ERROR` | 422 | Тело или параметры не той формы — подробности в `fields` | Исправить запрос |
| `RATE_LIMITED` | 429 | Превышен лимит запросов | Повторить после паузы из `Retry-After` |
| `NEW_CLIENTS_DAILY_LIMIT` | 429 | Исчерпан суточный лимит новых клиентов | Повторить на следующие сутки |
| `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 | У клиента уже была подписка | — |
| `TRIAL_DAILY_LIMIT` | 429 | Исчерпан суточный лимит пробных периодов | Повторить на следующие сутки |
| `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` |
| Новые клиенты | 500 в сутки | `429 NEW_CLIENTS_DAILY_LIMIT` |
| Пробные периоды | 50 в сутки | `429 TRIAL_DAILY_LIMIT` |
| Перевыпуск ссылки | раз в час на клиента | `429 LINK_ROTATE_TOO_SOON`, `Retry-After` |

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

## Версии

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