## Сбросить лимиты по праву акции

`POST /v1/cowork/limits/reset`

Тратит одно право сбросить лимиты Cowork/Code: расход всех трёх окон квоты — пятичасового, недельного и месячного — на месте пользователя обнуляется. Границы окон, дата следующего списания и временное увеличение лимитов не меняются.

Право выдаётся по акциям платформы и действует до окончания своей акции. Пользователь и аккаунт берутся из привязки ключа, параметров пути нет. Операция необратима: потраченное право не возвращается.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `rightId` | string | да | Идентификатор права — `limitReset.rights[].id` из [сводки по подписке](/docs/cowork/me), от 1 до 64 символов. Передавайте первое пригодное право — с `seatAlreadyReset: false`: такие идут в списке первыми, и среди них раньше стоит то, что раньше сгорит. Пригодного права нет — кнопку не показывать. Значение служит ключом идемпотентности: повтор с тем же `rightId` второе право не тратит |

## Примеры

Ось авторизации одна: эндпоинт принимает только ключ десктопа Cowork/Code. Личный ключ и ключ приложения получают `403 INSUFFICIENT_SCOPE` либо `403 COWORK_DESKTOP_KEY_REQUIRED`.

### curl — ключ десктопа Cowork/Code

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/cowork/limits/reset \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rightId": "cmg2k8x1f0003qz0l7a9b4c2d"}'
```

### JavaScript — ключ десктопа Cowork/Code

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/limits/reset', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_COWORK_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rightId: 'cmg2k8x1f0003qz0l7a9b4c2d' }),
})

if (!res.ok) {
  const { error } = await res.json()
  // 404 и 409 — перечитать сводку по подписке и показать то, что она вернёт.
  console.error(error.code)
} else {
  const { data } = await res.json()
  // alreadyUsed: true — обычный экран успеха: право потрачено раньше.
  console.log(`Лимиты сброшены: ${data.usedAt}`)
}
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при трате и при повторе |
| `data.rightId` | string | Идентификатор права из запроса |
| `data.usedAt` | string | Когда право потрачено (ISO 8601). При повторе — момент первой траты |
| `data.alreadyUsed` | boolean | `true` — право потрачено раньше, и этот вызов расход не обнулял. `false` — расход обнулён этим вызовом |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "rightId": "cmg2k8x1f0003qz0l7a9b4c2d",
    "usedAt": "2026-10-02T09:15:42.118Z",
    "alreadyUsed": false
  }
}
```

## Пример ответа при ошибке

409 — акция права закончилась или право отозвано:

```json
{
  "success": false,
  "error": {
    "code": "COWORK_LIMIT_RESET_RIGHT_EXPIRED",
    "message": "The limit-reset right is no longer available: its promotion has ended or the right was revoked."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_BODY` | В теле нет строкового `rightId`, оно пустое, длиннее 64 символов либо рядом лежит поле, которого тело не принимает |
| 400 | `INVALID_JSON_BODY` | Тело передано, но не читается как JSON |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан: такой строки на платформе нет |
| 401 | `KEY_INACTIVE` | Ключ отозван или выключен |
| 401 | `KEY_EXPIRED` | Срок действия ключа истёк |
| 402 | `ACCOUNT_FROZEN` | Счёт аккаунта заморожен за долг. Право не потрачено: после пополнения баланса его можно использовать до окончания акции |
| 403 | `INSUFFICIENT_SCOPE` | У ключа нет скоупа `vibe:cowork` |
| 403 | `COWORK_DESKTOP_KEY_REQUIRED` | Ключ другого класса: личный ключ, ключ приложения, ключ места агента или проектный ключ деплоя |
| 403 | `KEY_NOT_BOUND_TO_USER` | Ключ не привязан к пользователю аккаунта |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ выпущен только для чтения |
| 403 | `COWORK_LIMIT_RESET_DISABLED` | Сброс лимитов по праву акции для аккаунта не включён. Блока `limitReset` в сводке по подписке в этом случае тоже нет |
| 404 | `COWORK_LIMIT_RESET_RIGHT_NOT_FOUND` | Права с таким идентификатором у пользователя нет |
| 409 | `COWORK_LIMIT_RESET_RIGHT_EXPIRED` | Акция права закончилась, завершена досрочно либо право отозвано |
| 409 | `COWORK_LIMIT_RESET_SEAT_NOT_ACTIVE` | Место пользователя не работает: приостановлено, закрыто или ждёт нового владельца. Право не потрачено |
| 409 | `COWORK_LIMIT_RESET_SEAT_ALREADY_RESET` | Это место уже сбрасывали по той же акции — например, его передал коллега, который сбросил лимиты до передачи. Право не потрачено |
| 429 | `RATE_LIMITED` | Суммарный лимит платформы — 10 запросов в минуту. Действующее для вашего ключа значение приходит в заголовке `x-ratelimit-limit` — оно ниже суммарного, поскольку лимит делится между репликами. Повторите запрос после паузы |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code отключён на уровне платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**`rightId` — ключ идемпотентности, поэтому сбой сети повторяют с тем же значением.** Повтор после успешной траты отвечает `200` с `alreadyUsed: true` и моментом первой траты — это обычный экран успеха. Сбой сети и ответ `5xx`, кроме `503 COWORK_FEATURE_DISABLED`, повторяйте до трёх раз с тем же `rightId` и случайной паузой. `400`, `401` и `403` не повторяйте.

**После `404` и `409` перечитайте [сводку по подписке](/docs/cowork/me).** Право могло сгореть или быть отозвано между опросами, место — перестать работать. Сводка покажет, что осталось, и следующее право, если оно есть.

**Проценты квоты в ответ не входят.** После успеха перечитайте [полное состояние](/docs/cowork/state) и сводку по подписке: расход трёх окон уже нулевой, и признак исчерпания снят.

**Блока `limitReset` может не быть.** Он приходит в сводке и полном состоянии, только когда сброс лимитов по праву акции включён для аккаунта. Нет блока — нет и возможности: кнопку не показывать.

**Тратить может только ключ десктопа.** Ключ места агента видит блок прав, но потратить право не может: сброс — разовое действие человека перед экраном.

**Право привязано к пользователю в аккаунте, а не к тарифу.** Смена тарифа, приостановка и возобновление подписки право не трогают, но потратить его можно только на работающем месте.

## Смотрите также

- [Сводка по подписке Cowork/Code](/docs/cowork/me)
- [Состояние подписки Cowork/Code](/docs/cowork/state)
- [Предрасчёт смены тарифа](/docs/cowork/subscription-preview)
- [Cowork/Code](/docs/cowork)
- [Ошибки](/docs/errors)