Skip to main content
If the network drops after sending, you do not know whether the pre-test was created. Repeating the call without protection could create and charge twice. The Idempotency-Key header solves this.

Rules

  • The header is required on POST /pretests. Without it, the response is idempotency_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 the Idempotent-Replayed: true header. Nothing is created or charged again.
  • Same key and different body: the response is 409 idempotency_conflict.
  • Key of a pre-test that was deleted: the response is 409 idempotency_key_retired. Use another key.
Generate a new value for each pre-test (a UUID works) and store it with your own record before sending. To repeat, reuse exactly the same value and the same body.

5xx error and timeout on creation

A 5xx 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 with quota_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 considers uploadId, 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.