> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myunite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência

> Como repetir uma criação com segurança usando Idempotency-Key.

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`](https://docs.myunite.ai/errors#idempotency_key_required).
* O valor tem de 1 a 255 caracteres ASCII visíveis (sem espaços). Valor fora disso responde [`invalid_request`](https://docs.myunite.ai/errors#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`](https://docs.myunite.ai/errors#idempotency_conflict).
* **Chave de um pré-teste que foi excluído**: a resposta é `409` [`idempotency_key_retired`](https://docs.myunite.ai/errors#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.

```bash curl theme={null}
curl -i -X POST https://myunite.ai/api/v1/pretests \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Idempotency-Key: 6f0c2b1e-verao-relogio-urbano" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "upl_0123456789abcdef0123456789abcdef.png",
    "title": "Verão · relógio urbano",
    "channel": "ooh",
    "ooh": { "format": "FORMATO_DO_CATALOGO" }
  }'
```

```javascript JavaScript theme={null}
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde antes de enviar

async function createPretest() {
  return fetch("https://myunite.ai/api/v1/pretests", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.UNITE_API_KEY}`,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      uploadId: "upl_0123456789abcdef0123456789abcdef.png",
      title: "Verão · relógio urbano",
      channel: "ooh",
      ooh: { format: "FORMATO_DO_CATALOGO" },
    }),
  });
}

const first = await createPretest();
// Se a conexão cair e você não sabe o resultado, repita com a mesma chave:
const again = await createPretest();
console.log(again.headers.get("Idempotent-Replayed")); // "true" se já existia
```

```python Python theme={null}
import os
import uuid
import requests

idempotency_key = str(uuid.uuid4())  # guarde antes de enviar

def create_pretest():
    return requests.post(
        "https://myunite.ai/api/v1/pretests",
        headers={
            "Authorization": f"Bearer {os.environ['UNITE_API_KEY']}",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "uploadId": "upl_0123456789abcdef0123456789abcdef.png",
            "title": "Verão · relógio urbano",
            "channel": "ooh",
            "ooh": {"format": "FORMATO_DO_CATALOGO"},
        },
    )

first = create_pretest()
# Se a conexão cair e você não sabe o resultado, repita com a mesma chave:
again = create_pretest()
print(again.headers.get("Idempotent-Replayed"))  # "true" se já existia
```

## 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`](https://docs.myunite.ai/errors#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.