---
title: "POST /orders/{order}/items/retry-failed — Retry Failed Order Items"
url: https://lumean.app/de/developers/docs/api/post-orders-order-items-retry-failed
locale: de
description: "Retry Failed Order Items"
generated: 2026-10-17
operationId: orderItem.retryFailed
method: POST
path: "/orders/{order}/items/retry-failed"
scopes: [orders.write]
spec_version: 0.0.1
---

# 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.

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`.

- Benötigtes Recht: `orders.write`

## Anfrage

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

## Parameter

| Feld | In | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `order` | path | `string` | Pflicht | 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`. default: `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c` |

## Request-Body

Kein Body.

## Antworten

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

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `success` | `boolean` | Pflicht | 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. |
| `message` | `string` | Pflicht | 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. |
| `data` | `object` | Pflicht | The response payload. |
| `data.queued_count` | `integer` | Pflicht | How many fragments were accepted for a re-run. |
| `data.queued` | `array<any>` | Pflicht | What exactly was queued. Track progress on the order as a whole; there are no per-fragment events. |
| `data.skipped_count` | `integer` | Pflicht | How many fragments could not be re-run. A non-zero value is a normal outcome, not an error: some reasons are not fixable. |
| `data.skipped` | `array<any>` | Pflicht | The skipped fragments, each with its reason. |

**Beispiel**

```json
{
  "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."
      }
    ]
  }
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `success` | `boolean` | Pflicht | Always `false` in error responses. |
| `message` | `string` | Pflicht | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | Pflicht | Always `null` when the request is rejected before processing. |

**Beispiel**

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

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

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `message` | `string` | Pflicht | Error overview. |

**Beispiel**

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

### 404 — Not found, or not reachable with this key.

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `message` | `string` | Pflicht | Error overview. |

**Beispiel**

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

---

- Diese Seite im Browser: https://lumean.app/de/developers/docs/api/post-orders-order-items-retry-failed
- Vollständige maschinenlesbare Referenz: https://api.lumean.app/docs/llm.md