---
title: "Image Errored"
method: POST
path: "/image.errored"
tags: ["Image Events"]
---

# Image Errored

`POST /image.errored`

The request example illustrates what your webhook endpoint should expect.

## Headers

- `magic-hour-event-signature` string, required — A signatured created with the webhook secret key and a signed_payload, using HMAC with SHA-256
- `magic-hour-event-timestamp` string, required — Time in seconds since the epoch. Use this value to check whether the request is within a reasonable window of the current time. Usually less than 5 minutes.

## Request body

- object
  - `type` 'image.errored', required
  - `payload` object, required — Success
    - `id` string, required — Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads.
    - `name` string, nullable, required — The name of the image.
    - `status` 'draft' | 'queued' | 'rendering' | 'complete' | 'error' | 'canceled', required — The status of the image. - `draft` - the project was created but has not been submitted for rendering - `queued` - the job is waiting for an available server - `rendering` - the job is being processed; the `image.started` webhook event fires when rendering begins - `complete` - the job finished successfully; fires `image.completed` - `error` - the job failed during processing; fires `image.errored` - `canceled` - the job was manually canceled (for example from the Magic Hour web app) **Note:** `rendering`, `complete`, and `error` have matching webhook events; `canceled` does not - a canceled job emits no webhook event, so poll this endpoint to detect cancellation.
    - `image_count` integer, required — Number of images generated
    - `type` string, required — The type of the image project. Possible values are FACE_EDITOR, AI_IMAGE_EDITOR, AI_SELFIE, AI_HEADSHOT, AI_INFLUENCER, AI_IMAGE, AI_MEME, CLOTHES_CHANGER, BACKGROUND_REMOVER, FACE_SWAP, IMAGE_UPSCALER, IMAGE_ENHANCER, AI_GIF, QR_CODE, PHOTO_EDITOR, PHOTO_COLORIZER, HEAD_SWAP, BODY_SWAP, STORYBOARD, IMAGE_EXPANDER
    - `created_at` string, date-time, required
    - `enabled` boolean, required — Whether this resource is active. If false, it is deleted.
    - `credits_charged` integer, required — The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. If an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund.
    - `downloads` object[], required
      - `url` string, uri, required
      - `expires_at` string, date-time, required
    - `error` object, nullable, required — In the case of an error, this object will contain the error encountered during video render
      - `message` string, required — Details on the reason why a failure happened.
      - `code` string, required — An error code to indicate why a failure happened.

## Response `200`

Success

- object — Success
  - `message` string, required

## Other responses

- `400` — Error
- `500` — Error

## Changes

- **2026-01-24** `305b7dac8333` — 1 warning
  - removed the request property `payload/total_frame_cost`

[Change history](https://skmtc.dev/magichourhq/apis/magic-hour-webhook/changes/image.errored/post.md)

---

[API](https://skmtc.dev/magichourhq/apis/magic-hour-webhook.md) · [All operations](https://skmtc.dev/magichourhq/apis/magic-hour-webhook/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/magichourhq/magic-hour-webhook/revisions/15da4364f27e/schema)