api
Idempotency
One key per new request, the same key for its retries.
Updated · API v1
The Idempotency-Key header
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.