Idempotency

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

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

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

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.

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

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

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.

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. POST /v2/profiles keeps its own set too.

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.

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

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

POST /v2/profiles takes a key as an option, because a profile with only a name is valid and a retry without a key creates a second profile. A taken email, external_id or social handle returns 409 whether or not you send a key, and additional_data.field names the field.