<!-- Markdown twin of https://pixelvault.dev/docs/idempotency/ -->

# Idempotency

Networks fail after the server has done the work: the upload landed, but the response never reached you. Send an `Idempotency-Key` header on an upload and you can retry the exact same request without storing, counting, or billing a second copy. The retry returns the original asset.

Idempotency keys are supported on uploads that create media: [`POST /v1/images`](/docs/api/images/#upload_image), [`POST /v1/videos`](/docs/api/videos/#upload_video), [`POST /v1/videos/uploads`](/docs/api/videos/#create_video_upload) (resumable video), and [`POST /v1/audio`](/docs/api/audio/#upload_audio). They need a key-authenticated request: keyless image uploads validate the header's format but ignore it, and [batch uploads](/docs/api/images/#batch_upload) don't accept it (a batch is already idempotent per collection `type` + `name`).

## Send a key

A key is 1–255 printable ASCII characters with no spaces (a malformed key is `400 validation_error`). Use something derived from the work you're doing (`release-notes-hero-v1`, a job id, a UUID you persist before the first attempt), and send the same value on every retry.

Example

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Idempotency-Key: release-notes-hero-v1" \
  -F "file=@hero.png"
```

## What a retry returns

Situation

Response

First request with this key

The normal success response (`201`)

Same key, same inputs, original succeeded

`200` with the stored asset and `"replayed": true`

Same key, different inputs

`422 idempotency_key_reuse`

Video/audio: same key while the first request is still uploading

`409 idempotency_in_progress` (the error carries `upload_id`, `asset_id`, `expires_at`); retry later

Video/audio: the asset created with this key was deleted

`410 idempotency_result_deleted`

A replay describes the asset as it was stored, not the parameters of the retry. Fields applied only to new assets (custom `metadata`, `describe=true`) are ignored on a replay: change metadata later with `PATCH`.

```
{
  "data": {
    "id": "img_abc123",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
    "replayed": true
  }
}
```

## Conflicts: 422 idempotency\_key\_reuse

Reusing a key with different inputs returns `422 idempotency_key_reuse` on images, videos and audio alike. That refusal is deliberate: returning a URL for the wrong asset would be worse than failing. Use a new key for a new upload.

```
HTTP/1.1 422 Unprocessable Content

{
  "error": {
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with different video inputs."
  }
}
```

What counts as "different" depends on the media type:

Images

Video and audio

Compared inputs

Image bytes and visibility; also refused once a temporary image has passed its `expires_in`

Source (bytes or URL), filename, size, visibility, social-ready flag, TTL, folder, collection, metadata

Key retention

As long as the image exists

24 hours: an unfinished upload session expires 24 hours after it starts, and a completed upload's replay marker is kept 24 hours after completion

Checksum header

None: the server hashes the bytes

Direct byte uploads with a key must send `X-PixelVault-Content-SHA256` (64 hex chars). Missing: `400 idempotency_checksum_required`; bytes don't match: `400 checksum_mismatch`. URL imports need no checksum.

Concurrent duplicates

Both run; the loser returns the winner's image as a replay

`409 idempotency_in_progress` until the first finishes

### Video and audio checksums

For direct byte uploads, compute the SHA-256 of the file once and send it with the key. PixelVault verifies it while streaming, so a corrupted retry can never be mistaken for the original:

```
SHA256=$(shasum -a 256 launch-demo.mp4 | awk '{print $1}')
curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: video/mp4" \
  -H "Content-Length: $(wc -c < launch-demo.mp4)" \
  -H "X-PixelVault-Filename: launch-demo.mp4" \
  -H "X-PixelVault-Content-SHA256: $SHA256" \
  -H "Idempotency-Key: release-demo-v1" \
  --data-binary @launch-demo.mp4
```

Resumable video uploads take the whole-file `sha256` in the `POST /v1/videos/uploads` body instead of the header. Re-initiating an active session with the same key returns `200` with the same `upload_id` and `replayed: true`, so you can resume; once completed it returns the committed asset. Each part of a keyed session needs `X-PixelVault-Part-SHA256` (`400 part_checksum_required` otherwise); re-sending a stored part with the same bytes returns `replayed: true`, different bytes return `409 part_already_uploaded`. `POST …/complete` is naturally replayable after a lost success response. See the [large-file walkthrough](/docs/guides/social-ready-video/#large-files).

## Idempotency is not deduplication

An idempotency key makes one logical request retry-safe; different keys always create distinct assets, and content is never deduplicated across owners or privacy boundaries. For images only, `dedupe=true` is the content-reuse option: an existing image with identical bytes, visibility, folder and at least the lifetime you ask for is returned (`200`, `"deduplicated": true`) and nothing is stored or counted. Dedup is best-effort (simultaneous uploads of the same bytes can each be stored), and `dedupe` cannot be combined with `Idempotency-Key` (`400 validation_error`). Video and audio have no `dedupe` option.

## Next steps

-   [Error reference for `idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse).
-   [Upload video](/docs/guides/social-ready-video/) with checksums and resumable sessions.
-   [Why retry-safe uploads matter for agents](/blog/retry-safe-image-uploads/).
