Pular para o conteúdo principal
Se a rede cair depois do envio, você não sabe se o pré-teste foi criado. Repetir a chamada sem proteção poderia criar e cobrar duas vezes. O cabeçalho Idempotency-Key resolve isso.

Regras

  • O cabeçalho é obrigatório em POST /pretests. Sem ele, a resposta é idempotency_key_required.
  • O valor tem de 1 a 255 caracteres ASCII visíveis (sem espaços). Valor fora disso responde invalid_request.
  • O escopo é o workspace: a mesma chave em dois workspaces são duas criações diferentes.
  • Mesma chave e mesmo corpo: a API devolve o mesmo pré-teste, com 202, e o cabeçalho Idempotent-Replayed: true. Nada é criado nem cobrado de novo.
  • Mesma chave e corpo diferente: a resposta é 409 idempotency_conflict.
  • Chave de um pré-teste que foi excluído: a resposta é 409 idempotency_key_retired. Use outra chave.
Gere um valor novo para cada pré-teste (um UUID serve) e guarde-o junto do registro do seu lado antes de enviar. Para repetir, reutilize exatamente o mesmo valor e o mesmo corpo.

Erro 5xx e timeout ao criar

Uma resposta 5xx (ou um timeout) em POST /pretests não prova que nada foi criado: o pré-teste pode ter sido criado antes da falha. Repita sempre com a mesma Idempotency-Key e o mesmo corpo. Com a mesma chave, a API devolve o pré-teste já criado, se existir, ou tenta a criação de novo. Uma chave nova pode criar, e cobrar, um segundo pré-teste.

Falha por cota

Se a criação falhar por quota_exhausted e depois o saldo for restabelecido, repetir a mesma Idempotency-Key com o mesmo corpo tenta de novo a criação e pode usar uma unidade da cota. Isso é esperado: a primeira tentativa não consumiu nada.

O corpo conta

Para comparar uma chamada repetida, a Unite considera uploadId, title, brandId, o canal e os campos dele. Se quiser mudar qualquer um deles, use uma chave nova. O campo metadata não conta: repetir a chamada com outro metadata não gera conflito, e o pré-teste devolvido mantém o metadata da primeira chamada. O campo metadata vazio ({}) equivale a omitir o campo. Uma repetição com o mesmo corpo devolve o mesmo pré-teste mesmo que, depois da primeira chamada, a marca tenha sido renomeada ou o arquivo enviado tenha sido removido.