---
title: "POST /orders/{order}/items/{item}/retry — Повторить чанк"
url: https://lumean.app/developers/docs/api/post-orders-order-items-item-retry
locale: ru
description: "Повторить чанк"
generated: 2026-11-08
operationId: orderItem.retry
method: POST
path: "/orders/{order}/items/{item}/retry"
scopes: [orders.write]
spec_version: 1.0.0
---

# POST /orders/{order}/items/{item}/retry

**Повторить чанк**

Повторно отправляет на обработку сбойный чанк заказа. Применимо к чанку в статусе
`policy_flagged` **или** `failed`, когда сам заказ — `partially_completed`.
Так «дотягивают» частично выполненный заказ до `completed` — поштучно, по каждому
сбойному чанку (order-level `POST /orders/{order}/retry` для этого НЕ подходит: он
создаёт новый заказ и требует `completed`/`result_delivered`).

**Биллинг:** в пределах уже оплаченной длины (`free_length`) использует
заблокированный остаток оригинального чанка — новых средств и токен-квоты
ключа НЕ расходует. Текст ДЛИННЕЕ оплаченного тарифицируется доплатой за
превышение: она списывается quota-first, учитывается в токен-квоте ключа
(только дельта) и возвращается, если повтор не удался.

**Поле `text` (опциональное):** заменяет текст чанка. Длину и оба предела
отдаёт `GET .../items/{item}/text`: `free_length` — бесплатный объём,
`max_billable_length` — предел с доплатой, `max_raw_length` — ёмкость
фрагмента (её оплатой не снять) в единице `capacity_unit` (`chars` или
`utf8_bytes` — у Fish Audio). Бесплатны и места не занимают только наши
паузы `{{pause=2s}}`; `<break .../>` и указания диктору в `[…]` (`[шёпот]`) —
синтаксис провайдера: они тарифицируются и входят в лимит (llm.md §8.3).
Если не передать — повторяется **тот же** текст; если он уже удалён по сроку
хранения заказа — `422` с `reason: input_expired` (с новым `text` повтор проходит).

> **policy_flagged:** контент отклонён политикой провайдера (напр. ElevenLabs).
> Повтор с тем же текстом будет отклонён снова — передайте `text` с исправленной
> формулировкой. Конкретную причину API не сообщает (см. `GET .../items/{item}`),
> правьте по своему усмотрению (уберите/перефразируйте потенциально проблемный фрагмент).
> **failed:** техническая ошибка — обычно достаточно повторить (можно с укороченным
> текстом). Лимит попыток чанка — `ORDERS_MAX_RETRY_ATTEMPTS` (по умолчанию 5).

**Требуемое право ключа:** `orders.write`. Недоступно для `sfx`/`music`.

- Право ключа: `orders.write`

## Запрос

```bash
curl -X POST 'https://api.lumean.app/api/public/orders/{order}/items/{item}/retry' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `order` | path | `string` | обяз. | UUID заказа — 36 символов вида `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, не число. Берётся из поля `id`: его возвращает `POST /orders` при создании и `GET /orders` в списке. Чужой заказ по вашему ключу не откроется — придёт `404`. |
| `item` | path | `string` | обяз. | UUID фрагмента заказа (чанка) — 36 символов, не число и не порядковый номер. Берётся из поля `id` элемента: `GET /orders/{order}/items` отдаёт список, тот же набор лежит в `items[]` детального ответа заказа. Порядковый номер фрагмента — это соседнее поле `chunk_index`, в путь оно НЕ подставляется. |
| `X-Locale` | header | `string` | — | Язык локализованных текстов ответа (`message`, подписи, причины ошибок), код ISO-639-1. Необязателен; без него — язык аккаунта владельца ключа, затем `Accept-Language`, затем язык по умолчанию. Неизвестный или неподдерживаемый код пропускается так же, как отсутствующий. |
| `X-Timezone` | header | `string` | — | IANA-зона (`Europe/Moscow`), в которой ответ показывает моменты времени — ISO-8601 со смещением. Необязателен; без него даты приходят в UTC. Невалидная зона игнорируется. Применённую зону сервер возвращает в одноимённом заголовке ответа. |

## Тело запроса

Тело не обязательно: без него фрагмент повторяется с прежним текстом. Поле `text`
нужно после отказа контентной политики (`policy_flagged`) — тот же текст будет
отклонён снова.

В пределах оплаченной длины (`free_length` из `GET …/items/{item}/text`) повтор
бесплатен — цену наследует исходный фрагмент. Текст длиннее оплаченного (до
`max_billable_length`) тарифицируется доплатой за превышение; не хватает денег — `402`.

Content-Type: `application/json`

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `text` | `string` — ≤ 50000 симв. — nullable | — | Исправленный текст чанка. Не передан — чанк повторяется с прежним текстом. Для чанка в статусе `policy_flagged` (контент отклонён политикой провайдера) **повтор с тем же текстом будет отклонён снова** — присылайте переформулированный. Текущий текст чанка: `GET /orders/{order}/items/{item}/text`. |

**Пример**

```json
{}
```

## Сценарии тела

### Повтор как есть

Для чанка в статусе failed (техническая ошибка) — обычно достаточно повторить прежний текст.

```json
{}
```

### С исправленным текстом

Для policy_flagged: повтор с тем же текстом будет отклонён снова — присылайте переформулированный.

```json
{
  "text": "Переформулированный фрагмент текста."
}
```

## Ответы

### 201 — Чанк отправлен на повтор. Заказ остаётся в `partially_completed`, пока не завершатся все чанки.

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. |
| `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. |
| `data` | `OrderItem` | обяз. | Новая запись повтора со своим `id`; `parent_item_id` указывает на исходный фрагмент. Повтор бесплатен — новых токенов он не стоит. |
| `data.id` | `string` | обяз. | UUID чанка. Подставляется в пути `/orders/{order}/items/{item}/…`. |
| `data.order_id` | `string` | обяз. | UUID заказа, которому принадлежит чанк. |
| `data.item_type` | `string` | обяз. | Природа записи: `chunk` — исходный фрагмент, `retry` — бесплатный повтор упавшего фрагмента, `regeneration` — платная переделка готового. Повторы и перегенерации живут отдельными записями с тем же `chunk_index`: история попыток сохраняется целиком, а звучит в результате последняя. |
| `data.chunk_index` | `integer` — nullable | обяз. | Порядковый номер фрагмента в заказе, с нуля. Задаёт порядок склейки итогового файла. |
| `data.paragraph_index` | `string` | обяз. | Номер абзаца, к которому относится фрагмент, — заполняется только у исходных фрагментов абзацного заказа. `null` и в обычном режиме, и у записей повтора либо перегенерации: у них своей привязки к абзацу нет, её берут у родительского фрагмента через `parent_item_id`. Режим включается ключом `generation_mode` в `config_override` заказа. |
| `data.parent_item_id` | `string` | обяз. | UUID исходного чанка — у записей `retry` и `regeneration`. У самого исходного чанка `null`. |
| `data.original_text_length` | `integer` | обяз. | Длина текста, с которой фрагмент создавался. Служит потолком для `text` в `regenerate`. |
| `data.current_text_length` | `integer` | обяз. | Длина актуального текста фрагмента: после перегенерации отличается от `original_text_length`. |
| `data.price_units` | `integer` | обяз. | Стоимость фрагмента в **токенах** — это не деньги. Денежная сумма лежит у самого заказа, в его поле `price_units` (там LMC, здесь токены; поля называются одинаково, единицы разные). |
| `data.consumed_units` | `integer` | обяз. | Сколько токенов фактически списано по этому фрагменту. У незавершённого фрагмента — 0. |
| `data.remaining_locked` | `integer` | обяз. | Сколько токенов ещё зарезервировано под фрагмент. Обнуляется, когда фрагмент завершается или отменяется. |
| `data.status` | `string` | обяз. | Состояние фрагмента: `pending` — ждёт воркера, `processing` — в работе, `completed` — готов, `failed` — техническая ошибка, `policy_flagged` — отклонён контентной политикой. Разница между двумя последними определяет способ лечения: `failed` чинится повтором как есть, `policy_flagged` — только переформулировкой текста, повтор с прежним будет отклонён снова. Попытка `policy_flagged` у ElevenLabs не бесплатна: она расходует ресурс провайдера и без результата, поэтому из суммы, которая вернулась бы за фрагмент, удерживается фиксированная плата за попытку (на заказах из квоты — эквивалент в токенах). Удерживается только из возвращаемого — сверх заблокированного по заказу не списывается ничего, баланс в минус не уходит. Денежная часть видна в истории операций как `policy_block_fee`; из квоты просто возвращается меньше токенов. |
| `data.result_file` | `object \| string \| null` — nullable | обяз. | Файл готового фрагмента: абсолютный путь либо структура с путём и размером. Скачивается через `POST /storage/url`, как и файлы заказа. `null`, пока фрагмент не готов. |
| `data.duration_ms` | `integer` — nullable | обяз. | Длительность полученного аудио в миллисекундах — длина записи, а не время генерации. У не-аудио задач `null`. |
| `data.attempt_number` | `integer` | обяз. | Номер попытки для этого фрагмента, начиная с 1. Растёт с каждым повтором. |
| `data.can_retry` | `boolean` | обяз. | Разрешён ли бесплатный повтор прямо сейчас. Учитывает статус, тип задачи и исчерпание попыток — проверять условия самому не нужно. |
| `data.can_regenerate` | `boolean` | обяз. | Разрешена ли платная перегенерация прямо сейчас. Доступна только для завершённых фрагментов. |
| `data.created_at` | `string` — date-time — nullable | обяз. | Когда фрагмент создан, ISO 8601. |
| `data.updated_at` | `string` — date-time — nullable | обяз. | Когда фрагмент последний раз менялся, ISO 8601. |
| `data.failure_reason` | `string` — nullable | — | Причина падения фрагмента для показа пользователю — локализованный текст на языке запроса, не машинный код (ветвиться по нему нельзя, формулировки меняются). Есть только у `failed` и `policy_flagged`; остальным, а также когда причину определить не удалось, приходит `null`. |

**Пример**

```json
{
  "success": true,
  "message": "Order item retry created successfully.",
  "data": {
    "id": "a9b0c1d2-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
    "order_id": "e7f8a9b0-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
    "item_type": "retry",
    "chunk_index": 2,
    "parent_item_id": "f8a9b0c1-2d3e-4f4a-8b5c-6d7e8f9a0b1c",
    "original_text_length": 96,
    "current_text_length": 96,
    "price_units": 96,
    "consumed_units": 0,
    "remaining_locked": 96,
    "status": "pending",
    "result_file": null,
    "attempt_number": 2,
    "can_retry": false,
    "can_regenerate": false,
    "created_at": "2026-07-17T13:40:00+00:00",
    "updated_at": "2026-07-17T13:40:00+00:00"
  }
}
```

### 400 — Прочий отказ без машинного кода (редко): причина — только в `message`. Отказы с `reason` приходят кодами 402/409/422/503.

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `errors` | `null` — nullable | обяз. | Разбор по полям — только у ошибок валидации (`422`): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит `null`: разбирать нечего, причина целиком в `message`. |

**Пример**

```json
{
  "success": false,
  "message": "The operation could not be completed."
}
```

### 401 — Не авторизован (отсутствует/невалидный X-API-KEY)

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `data` | `null` — nullable | обяз. | Всегда `null`, когда запрос отклонён до обработки. |

**Пример**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

### 402 — Не хватает средств: `reason: insufficient_funds` — у чанка не осталось залоченного остатка; `insufficient_balance`/`insufficient_allowance` — не на что оплатить доплату за текст длиннее оплаченного.

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `reason` | `string` | обяз. | Машиночитаемая причина бизнес-отказа (например, `input_expired`, `insufficient_balance`). Ветвите обработку по ней, а не по тексту `message`. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "Insufficient balance.",
  "reason": "insufficient_balance",
  "error_code": "insufficient_balance"
}
```

### 403 — Нет доступа к заказу, у ключа нет права orders.write, либо нет подписки на сервис (`reason: no_subscription`)

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

### 404 — Заказ или элемент не найден

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

### 409 — Повтор этого чанка уже идёт (`reason: active_retry_exists`) либо заказ склеивается (`reason: stitch_in_progress`). Повторите позже.

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `reason` | `string` | обяз. | Машиночитаемая причина бизнес-отказа (например, `input_expired`, `insufficient_balance`). Ветвите обработку по ней, а не по тексту `message`. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "A retry for this item is already in progress.",
  "reason": "active_retry_exists",
  "error_code": "active_retry_exists"
}
```

### 422 — Повтор невозможен (`reason`): `invalid_order_status` — заказ не `partially_completed`; `invalid_status` — чанк не `failed`/`policy_flagged`; `max_attempts_reached` — исчерпан лимит попыток (5); `generative_not_supported` — `sfx`/`music`; `text_over_capacity`, `content_blocked`, `input_expired` — см. описание; `retry_config_outdated` — настройки заказа (снимок шаблона с `config_override`) не проходят текущую схему сервиса, повторить фрагмент «как был» нельзя — создайте новый заказ. Либо ошибка валидации тела (`errors`).

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Сводка ошибок валидации словами, на языке ответа (`X-Locale`). |
| `errors` | `object` | обяз. | Разбор по полям: ключ — поле запроса, значение — список претензий к нему. |
| `errors.*` | `array<string>` — произвольные ключи | — |  |

**Пример**

```json
{
  "message": "string",
  "errors": {
    "key": [
      "string"
    ]
  }
}
```

### 429 — Превышена токен-квота ключа (доплата за текст длиннее оплаченного)

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `reason` | `string` | обяз. | Машиночитаемая причина отказа — по ней ветвите обработку, а не по тексту сообщения. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают; ветвитесь по любому из них. |
| `retry_after` | `integer` — nullable | — | Через сколько секунд имеет смысл повторить запрос (то же значение — в заголовке `Retry-After`). |

**Пример**

```json
{
  "success": false,
  "message": "Too many attempts. Please wait a moment and try again.",
  "reason": "rate_limit_exceeded",
  "error_code": "rate_limit_exceeded",
  "retry_after": 30
}
```

### 503 — Приём работы на сервис временно приостановлен (`reason: service_maintenance`). Повторите позже.

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `reason` | `string` | обяз. | Машиночитаемая причина бизнес-отказа (например, `input_expired`, `insufficient_balance`). Ветвите обработку по ней, а не по тексту `message`. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "The service is temporarily unavailable due to maintenance. Please try again later.",
  "reason": "service_maintenance",
  "error_code": "service_maintenance"
}
```

---

- Эта же страница в браузере: https://lumean.app/developers/docs/api/post-orders-order-items-item-retry
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md