# Idempotency

> Retry order writes and review imports safely with the Idempotency-Key header, and learn how replays, conflicts and retention work.

Breadcrumb: API › Idempotency · Updated: 2026-10-19
Docs index: https://docs.cevoid.com/developers/llms.txt

A network error can leave you unsure whether a write went through. Order writes and review imports take an `Idempotency-Key` header, so you can send the same request again without creating or changing an order or a review twice.

## Which requests take a key

| Request | Key |
| --- | --- |
| `POST /v2/orders` | Required |
| `PATCH /v2/orders/{id}` | Required |
| `POST /v2/product-reviews` | Required |
| `POST /v2/company-reviews` | Required |
| `DELETE /v2/orders/{id}` | Not used: deleting an order twice returns `204` both times |
| Label writes (`POST`, `PATCH`, `DELETE /v2/labels…`) | Not used |

A request that needs a key and has none fails with `422 validation_error`, naming the field `headers.idempotency-key`.

## Send a key

Generate a new key for each operation, such as a UUID, and reuse it only to retry that same request:

```bash title="Create an order"
curl -X POST "https://api.cevoid.com/v2/orders" \
  -H "Authorization: Bearer $CEVOID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c0b9a1e-6f2d-4b8a-9e3c-7d1f5a2b8c60" \
  -d @order.json
```

A key is 1 to 255 characters, with no leading or trailing whitespace and no control characters.

## How a retry is answered

Cevoid remembers each key for seven days after the request first succeeds. Within that time:

| You send the same key with | Cevoid answers |
| --- | --- |
| The same request | The first response again, with the same body and the operation's success status (`201` for `POST`, `200` for `PATCH`). Nothing runs a second time, even if the order has changed since. |
| A different body, path or method | `409` with the code `conflict` and the message "Idempotency-Key was already used for a different request" |
| The same request while the first is still running | The same response as the first, once it has finished. The write happens once. |

- "The same request" compares the method, the path and the body after validation: key order in the JSON does not matter.
- Nothing marks a response as a repeat. If you need to know, compare the response with what you stored the first time.
- After seven days the key is forgotten, and a request with it runs again.

## Failed requests

Only successful writes are remembered. When a request fails, with a `4xx` or a `5xx` status, nothing is stored: send it again with the same key and it runs again. Fix the request first if it failed validation.

## Scope

Keys are shared by every API key of a workspace. `POST /v2/orders` and `PATCH /v2/orders/{id}` use one set of keys, so the same key on both returns `409`, and so does the same key on another order's `PATCH`.

Each review import keeps its own set: a key used with `POST /v2/product-reviews` does not clash with the same key on `POST /v2/company-reviews` or on an order write.

## Retries and rate limits

Every request counts against your write allowance, repeats included, because rate limiting runs before the key is checked. A `429` response never reaches the key check: retry it with the same key after the `Retry-After` delay. See [Rate limits](https://docs.cevoid.com/developers/api/rate-limits.md).

## Orders are also matched by their source

Independently of the key, `POST /v2/orders` recognizes an order by `source_connection_id` and `external_order_id`:

- The same order sent again with a new key returns the existing order with `201`.
- A different order with the same source identity returns `409` "A different Order already exists for this source identity".
- An order with the source identity of a deleted order returns `409` "This source order identity was previously deleted".

## Review imports are also matched by their source

Independently of the key, `POST /v2/product-reviews` and `POST /v2/company-reviews` refuse a review that is already in Cevoid. Both answer `409` with the code `review_already_exists` and the existing review's ID in `additional_data.review_id`:

- A review of the same kind with the same `source.platform` and `source.external_id` returns "Review source identity already exists".
- A reviewer who already has an active review of the same product, or an active company review, returns "Reviewer already has an active review for this subject".

## Related articles

- [Error handling](https://docs.cevoid.com/developers/api/errors.md)
- [Rate limits](https://docs.cevoid.com/developers/api/rate-limits.md)

---

Canonical: https://docs.cevoid.com/developers/api/idempotency