Idempotency

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

View as Markdown

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:

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.

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".