Guia

Idempotência

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:

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:

{
  "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.

📮 contact email: [email protected]