Idempotency-Key header solves this.
Rules
- The header is required on
POST /pretests. Without it, the response isidempotency_key_required. - The value has 1 to 255 visible ASCII characters (no spaces). A value outside that responds
invalid_request. - The scope is the workspace: the same key in two workspaces is two different creations.
- Same key and same body: the API returns the same pre-test, with
202, and theIdempotent-Replayed: trueheader. Nothing is created or charged again. - Same key and different body: the response is
409idempotency_conflict. - Key of a pre-test that was deleted: the response is
409idempotency_key_retired. Use another key.
5xx error and timeout on creation
A5xx response (or a timeout) on POST /pretests does not prove nothing was created: the pre-test may have been created before the failure. Always repeat with the same Idempotency-Key and the same body. With the same key, the API returns the already-created pre-test, if there is one, or attempts the creation again. A new key may create, and charge for, a second pre-test.
Quota failure
If creation fails withquota_exhausted and the balance is later restored, repeating the same Idempotency-Key with the same body attempts the creation again and may use one quota unit. This is expected: the first attempt consumed nothing.
The body counts
To compare a repeated call, Unite considersuploadId, title, brandId, the channel and its fields. If you want to change any of them, use a new key.
The metadata field does not count: repeating the call with different metadata does not cause a conflict, and the returned pre-test keeps the metadata of the first call. An empty metadata ({}) is the same as omitting the field.
A repeat with the same body returns the same pre-test even if, after the first call, the brand was renamed or the uploaded file was removed.