# Idempotência — Repetição Segura com o Cabeçalho Idempotency-Key

> Use o cabeçalho Idempotency-Key para repetir com segurança uploads de documentos, processamento em lote e acionamentos de bbox sem pagar ou executar a mesma operação duas vezes.

Chamadas de rede falham e expiram. Quando isso acontece com uma requisição que gasta créditos ou cria um recurso, repeti-la ingenuamente pode gastar esses créditos duas vezes. O cabeçalho `Idempotency-Key` resolve isso: envie a mesma chave em uma repetição e você receberá exatamente a mesma resposta da chamada original — sem que ela seja executada novamente.

## Como funciona

Adicione um cabeçalho `Idempotency-Key` com qualquer string única gerada pelo cliente (um UUID é uma boa escolha) a uma requisição que o suporte:

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e9a2c-9b41-4e6a-8c3d-2f1a5b6c7d8e" \
  -d '{"fields": [{"name": "invoice_number"}, {"name": "total_amount"}]}'
```

A chave é armazenada por `(sua conta, valor da chave, endpoint)` por **24 horas**. Se a mesma requisição (mesmo endpoint, mesma chave) chegar novamente dentro dessa janela, a resposta original — mesmo código de status, mesmo corpo — é reproduzida, e a operação em si não é executada uma segunda vez. Isso significa que uma chamada `process` repetida com a mesma chave não deduz créditos duas vezes, e um upload de `documents` repetido com a mesma chave não cria um segundo documento.

Requisições sem um cabeçalho `Idempotency-Key` se comportam exatamente como antes — nada é armazenado, nada é reproduzido. O cabeçalho é totalmente opcional.

## Quais endpoints suportam

Apenas endpoints que consomem créditos ou criam um recurso aceitam `Idempotency-Key` — não há benefício em usá-la em um `GET` somente leitura, pois repetir uma leitura já é seguro por si só:

- `POST /documents` (criação de documento)
- `POST /batches/{batch_name}/process` (inicia o processamento, deduz créditos)
- `POST /documents/{document_id}/bbox` (aciona a etapa paga de anotação de bbox)

## Reutilizar uma chave com parâmetros diferentes

Um `Idempotency-Key` serve para repetir a *mesma* requisição, não como um rótulo de uso geral. Se você reutilizar uma chave já usada, mas desta vez com parâmetros de requisição diferentes — um `batch_name` diferente, um corpo de requisição diferente — a API não reproduz silenciosamente a resposta antiga (o que seria incorreto para uma requisição diferente) e não adivinha qual delas você pretendia. Em vez disso, retorna um erro 400 `idempotency_key_reused`. Gere uma nova chave sempre que a requisição for genuinamente diferente, mesmo que tenha como alvo o mesmo tipo de operação.

## Exemplo: uma resposta reproduzida

A segunda chamada abaixo, feita com a mesma chave de uma chamada que já teve sucesso, retorna o mesmo corpo e código de status da primeira — ela não deduz créditos novamente:

```json
{
  "batch_name": "260716-4K9P",
  "queued": 2,
  "quality": "fast",
  "webhook_registered": false
}
```

## O que é registrado

Apenas respostas bem-sucedidas (2xx) são salvas para reprodução. Se a chamada original falhou — um erro de validação, créditos insuficientes, qualquer coisa não-2xx — nada é registrado, e repetir com a mesma chave simplesmente tenta a operação do zero. Isso é intencional: um erro é exatamente a situação em que se deseja que a nova tentativa realmente tente novamente, e não receba a mesma falha reproduzida até a chave expirar 24 horas depois.

---

Source: https://imagetotable.ai/pt/developers/guides/idempotency