Skip to content
Lumean API
POST/orders/{order}/items/retry-failed

Retry Failed Order Items

Queues a retry for every failed chunk of the order in one call — the bulk version of the per-chunk retry.

orders.writeasynchronous

Useful after a transient provider outage, when many chunks failed for the same technical reason. Chunks rejected by content policy (policy_flagged) will fail again unless the text changes: fix those individually via POST /orders/{order}/items/{item}/retry with a new text.

Answers 202: the plan is accepted, execution is asynchronous. The body carries queued (chunks sent for retry) and skipped, each skip with a machine-readable reason: superseded (a successful version already exists), active_retry_exists, policy_flagged, max_attempts_reached, insufficient_funds. There is no synchronous outcome — poll GET /orders/{order}/items or listen for the bulk_retry.completed WebSocket event.

Billing: free, like the per-chunk retry — it reuses the funds already locked by each chunk and does not consume the key's token quota.

Order-level refusals come back as {success: false, message, reason}: 409 stitch_in_progress; 422 invalid_order_status (the order is not partially_completed), generative_not_supported (sfx/music), nothing_to_retry or retry_config_outdated (the order's settings no longer pass the service's current schema — nothing is queued; create a new order); 503 service_maintenance (the service executing the order is paused). These refusals are synchronous: the plan is not accepted and no bulk_retry.completed follows.

Required key permission: orders.write.

On this page(4)

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-failed
  • stringin 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.

Possible responses

202

The plan was accepted and the failed chunks were queued for retry. Watch the order status.

Body example
{
  "success": true,
  "message": "Failed chunks queued for retry",
  "data": {
    "queued_count": 2,
    "queued": [
      {
        "item_id": "f8a9b0c1-2d3e-4f4a-8b5c-6d7e8f9a0b1c",
        "chunk_index": 2
      },
      {
        "item_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "chunk_index": 5
      }
    ],
    "skipped_count": 1,
    "skipped": [
      {
        "item_id": "d2e3f4a5-6b7c-4d8e-8f9a-1b2c3d4e5f6a",
        "chunk_index": 7,
        "reason": "max_attempts_reached",
        "reason_label": "The chunk has run out of retry attempts."
      }
    ]
  }
}
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

The response payload.

object
queued_countrequired

How many fragments were accepted for a re-run.

integer
queuedrequired

What exactly was queued. Track progress on the order as a whole; there are no per-fragment events.

array<any>
skipped_countrequired

How many fragments could not be re-run. A non-zero value is a normal outcome, not an error: some reasons are not fixable.

integer
skippedrequired

The skipped fragments, each with its reason.

array<any>
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
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

Events this produces

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

Nearby

The same in words

Feed this page to an AI

Open .mdllm.md

spec 0.0.1