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

Retry Order Item

Retries one failed chunk. This is how a partially_completed order is brought to completed — walk over every policy_flagged/failed chunk.

orders.writeasynchronous402 PAYG 409 conflict 429 limits

Billing: within the already paid length (free_length) the retry is paid for out of the funds already locked by the chunk — no new charge and no key token quota. A text LONGER than paid is charged for the excess (quota first, counted in the key's token quota — the delta only) and refunded if the retry fails. The limits come from GET /orders/{order}/items/{item}/text.

Two kinds of failure, handled differently:

failed — a technical error (worker timeout, generation glitch). Retrying the same text is usually enough: send an empty body.
policy_flagged — the provider rejected the content. The same text will be rejected again — fetch it via GET /orders/{order}/items/{item}/text, rephrase, and send it back in text.

Without text the previous text is retried; if it was already deleted with the order's storage retention, you get 422 with reason: input_expired (a retry with a new text goes through).

Not available for sfx/music: those are single-shot generations. Limit — 5 attempts per chunk.

Required key permission: orders.write.

On this page(5)

Parameters

The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.

POSThttps://api.lumean.app/api/public/orders//items//retry

orderstringin pathrequired
Order UUID — 36 characters shaped like 9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c, not a number.

Take it from the id field: POST /orders returns it on creation and GET /orders lists it. Someone else’s order will not open with your key — you get a 404.
The value goes straight into the request line above.
itemstringin pathrequired
Order chunk UUID — 36 characters; neither a number nor a position.

Take it from an item’s id field: GET /orders/{order}/items returns the list, and the same set sits in items[] of the detailed order response. The chunk’s position is the neighbouring chunk_index field, which does not go into the path.
The value goes straight into the request line above.

Request body

application/json

The body is optional: without it the fragment is retried with its previous text. The text field is what you need after a content-policy rejection (policy_flagged) — the same text would be rejected again.

Within the paid length (free_length from GET …/items/{item}/text) a retry is free — it inherits the original fragment’s price. A text longer than paid (up to max_billable_length) is charged for the excess; not enough money — 402.

Scenarios

Retry as-is With corrected text

With corrected text

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

Fields

textoptional

Corrected chunk text. If omitted, the chunk is retried with its previous text.

For a policy_flagged chunk (content rejected by the provider) the same text will be rejected again — send a rephrased one. The current text is available at GET /orders/{order}/items/{item}/text.

nullable≤ 50000 chars

string

Example Переформулированный фрагмент текста.

Possible responses

201

The chunk was queued for retry. The order stays partially_completed until every chunk settles.

Body example

{
  "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"
  }
}

Response fields

successrequired

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean

messagerequired

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string

datarequired

A new retry record with its own id; parent_item_id points at the original fragment. A retry is free — it costs no new tokens.

OrderItemOrderItem

idrequired

Chunk UUID. Use it in /orders/{order}/items/{item}/… paths.

string

order_idrequired

UUID of the order this chunk belongs to.

string

item_typerequired

What the record is: chunk is an original fragment, retry a free re-run of a failed one, regeneration a paid redo of a finished one.

Retries and regenerations are separate records sharing the same chunk_index: the full attempt history is kept, and the last one is what the result plays.

string

chunk_indexrequired

Zero-based position of the fragment within the order. It defines the order in which the final file is assembled.

nullable

integer

paragraph_indexrequired

The paragraph this fragment belongs to — filled in only for the original fragments of a paragraph-mode order. It is null both in ordinary mode and on retry or regeneration records: those carry no paragraph link of their own and inherit it from the parent fragment via parent_item_id. The mode is switched on by the generation_mode key in the order's config_override.

string

parent_item_idrequired

UUID of the source chunk — present on retry and regeneration records. null on an original chunk.

string

original_text_lengthrequired

Length of the text the fragment was created with. It is the ceiling for text in regenerate.

integer

current_text_lengthrequired

Length of the fragment’s current text: after a regeneration it differs from original_text_length.

integer

price_unitsrequired

Cost of the fragment in tokens — not money. The monetary amount lives on the order itself, in its own price_units field (LMC there, tokens here; the names match, the units do not).

integer

consumed_unitsrequired

How many tokens were actually charged for this fragment. Zero while the fragment is unfinished.

integer

remaining_lockedrequired

How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled.

integer

statusrequired

Fragment state: pending waits for a worker, processing is in flight, completed is done, failed hit a technical error, and policy_flagged was rejected by the content policy.

The difference between the last two dictates the fix: failed is cured by retrying as is, whereas policy_flagged requires rewording — retrying the same text is rejected again.

string

result_filerequired

The finished fragment’s file: an absolute path, or a structure carrying path and size. Download it via POST /storage/url, same as order files. null until the fragment is ready.

nullable

object | string | null

duration_msrequired

Duration of the produced audio in milliseconds — the length of the recording, not the generation time. null for non-audio tasks.

nullable

integer

attempt_numberrequired

Attempt number for this fragment, starting at 1. It grows with every retry.

integer

can_retryrequired

Whether a free retry is allowed right now. It already accounts for status, task type and exhausted attempts, so you need not re-check the conditions.

boolean

can_regeneraterequired

Whether a paid regeneration is allowed right now. Available for finished fragments only.

boolean

created_atrequired

When the fragment was created, ISO 8601.

nullabledate-time

string

updated_atrequired

When the fragment last changed, ISO 8601.

nullabledate-time

string

failure_reasonoptional

Machine-readable failure reason — present only on failed and policy_flagged. Everything else gets null.

nullable

string

400

Any other refusal without a machine code (rare): the reason is only in message. Refusals with a reason come as 402/409/422/503.

Body example

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

Response fields

successrequired

Always false in error responses.

boolean

messagerequired

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string

errorsrequired

A per-field breakdown — present only on validation errors (422): the key names a request field, the value lists the complaints about it. Other codes send null, since there is nothing to break down and the whole reason is in message.

nullable

null

401

The key is missing, unknown, disabled or expired.

Analyse this response

Body example

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

Response fields

successrequired

Always false in error responses.

boolean

messagerequired

Error text in the key's language (set through the X-Locale header).

string

datarequired

Always null when the request is rejected before processing.

nullable

null

402

Not enough money: reason: insufficient_funds — the chunk has no locked funds left; insufficient_balance/insufficient_allowance — nothing to pay the surcharge for a text longer than paid.

Analyse this response

Body example

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

Response fields

successrequired

Always false in error responses.

boolean

messagerequired

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string

reasonrequired

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string

error_coderequired

The same machine-readable code as in reason — a second name for the field. The values always match.

string

403

The key lacks the required permission, or the object belongs to another user.

Analyse this response

Body example

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

Response fields

messagerequired

Error overview.

string

404

Not found, or not reachable with this key.

Analyse this response

Body example

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

Response fields

messagerequired

Error overview.

string

409

A retry of this chunk is already running (reason: active_retry_exists) or the order is being stitched (reason: stitch_in_progress). Try again later.

Analyse this response

Body example

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

Response fields

successrequired

Always false in error responses.

boolean

messagerequired

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string

reasonrequired

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string

error_coderequired

The same machine-readable code as in reason — a second name for the field. The values always match.

string

422

Retry is not possible (reason): invalid_order_status — the order is not partially_completed; invalid_status — the chunk is not failed/policy_flagged; max_attempts_reached — the attempt limit (5) is exhausted; generative_not_supported — sfx/music; text_over_capacity, content_blocked, input_expired — see the description; retry_config_outdated — the order's settings (the template snapshot plus config_override) no longer pass the service's current schema, so the chunk cannot be retried as it was — create a new order. Or a body validation error (errors).

Analyse this response

Body example

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

Response fields

messagerequired

Errors overview.

string

errorsrequired

A detailed description of each field that failed validation.

object

*optional

arbitrary keys

array<string>

429

Limit exceeded: either the key's request rate or its token quota. Retry no earlier than Retry-After.

Analyse this response

Body example

{
  "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
}

Response fields

successrequired

Always false in error responses.

boolean

messagerequired

Error text in the key's language (set through the X-Locale header).

string

reasonrequired

Machine-readable failure reason — branch on this, not on the message text.

string

error_coderequired

The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.

string

retry_afteroptional

How many seconds to wait before retrying (the same value is in the Retry-After header).

nullable

integer

503

Work intake for the service is temporarily paused (reason: service_maintenance). Try again later.

Body example

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

Response fields

successrequired

Always false in error responses.

boolean

messagerequired

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string

reasonrequired

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string

error_coderequired

The same machine-readable code as in reason — a second name for the field. The values always match.

string

Events this produces

Progress arrives over WebSocket: polling the order in a loop is not required. Subscribing needs the same scope as reading orders.

The same in words

Retries and idempotency

Objects

OrderItem

Neighbouring operations

Feed this page to an AI

Open .md llm.md

spec 0.0.1

Parameters

Request body

Possible responses

Events this produces

Nearby

Feed this page to an AI