---
title: "job.item.failed"
method: POST
path: "job.item.failed"
---

# job.item.failed

`POST job.item.failed` (webhook)

Signed with the endpoint's secret in `ImageStep-Signature`; the same event id on every retry. Answer any 2xx to acknowledge it.

## Payload

- JobItemEvent: One item settled — only to endpoints that subscribed to item events
  - `id` string, required: The event's id, `evt_…` — the same on every retry of it, so a receiver can drop a repeat
  - `type` 'job.item.completed' | 'job.item.failed', required: What happened; it decides the shape of `data`
  - `apiVersion` 'v1', required: The version of this body's shape — the `v1` of the `/api/v1` paths. Inside it fields are only added (https://imagestep.dev/docs/changelog)
  - `createdAt` string, date-time, required: When the event was queued — not when this attempt was sent
  - `data` JobItemEventData, required: `job.item.completed` / `job.item.failed`: one item's outcome
    - `jobId` string, required: The job the item belongs to, `job_…`
    - `type` 'ai-generate' | 'ai-edit' | 'parse' | 'process' | 'render' | 'chain', required: The job's type
    - `op` string: The op the job was submitted as, when it was submitted as one
    - `index` integer, required: The item's position in the job, from 0 — `index` on the job's items
    - `itemIndex` integer, required: Deprecated: `index`, until 2027-01-12. https://imagestep.dev/docs/changelog#2026-10-14-webhook-names
    - `status` 'COMPLETED' | 'FAILED', required: How the item settled
    - `step` integer: `chain` only: the segment the item is on, from 0 — a chain's item is delivered once per segment
    - `failedStep` integer: `chain` only: the segment a failed item failed on, from 0 — where a resume restarts it
    - `settledItems` integer, required: Items of the job settled so far, this one included
    - `totalItems` integer, required: Items in the job
    - `resultAssetId` string: The asset it made, once `COMPLETED`; absent for `analyze`, whose product is `output`
    - `sourceAssetId` string: The asset it ran on; absent for an image generated from a prompt or a render row
    - `output` object: `analyze` only: the answer, in the default schema's shape or your `parameters.schema`
    - `error` string: A failed item: why, in one sentence for a person
    - `errorCode` string: A failed item: the code to branch on, from the closed set of error codes (§11)
    - `retryable` boolean: A failed item: whether a resume could succeed — the code's own flag

## Acknowledgement `2XX`

Received. Anything else, or no answer, is retried

---

[API](https://skmtc.dev/imagestep/apis/imagestep-api.md) · [All operations](https://skmtc.dev/imagestep/apis/imagestep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imagestep/apis/imagestep-api/revisions/5e8e922a3085?raw)