# Idempotency

Adspy API · https://www.adspy.sh/docs/api/idempotency · Updated October 24, 2026

One key per new request, the same key for its retries.

## The Idempotency-Key header

Header:

```http
Idempotency-Key: 4f3c9a52-9a1e-4b55-8d2f-2a6f0c3f8e17
```

- Required on every POST: without it the request answers 400 idempotency_key_required.
- 8 to 160 visible ASCII characters. A UUID v4 works.
- Keys are scoped to the API key: two keys never share a key's result.

## Retries

| You send | Adspy answers |
| --- | --- |
| The same key and the same body, after the first request finished | The first answer again, with Idempotent-Replayed: true. Nothing runs or counts twice. |
| The same key while the first request still runs | 409 operation_in_progress with Retry-After. |
| The same key with another body | 409 idempotency_conflict. |
| A new key | A new request. |

A replayed new collection answers even after your monthly quota is used up, because it is the same collection.

## GET and PATCH

GET requests have no side effects and need no key. PATCH /v1/collections/{id}/creatives/{creative_id} sets a note to a value: sending it twice leaves the same note. Saving creatives (POST /v1/collections and POST /v1/collections/{id}/creatives) is a set: a retry adds the same creatives to the same collection, so it changes nothing and is not marked Idempotent-Replayed.