Idempotência

O problema

A rede cai depois que o servidor processou, mas antes da resposta chegar. Você não sabe se o contato foi criado ou não. Repetir a requisição arrisca duplicar; não repetir arrisca perder. A Idempotency-Key resolve isso: a segunda chamada com a mesma chave devolve a resposta original em cache, sem executar nada de novo.

Onde funciona

A idempotência vale em quatro rotas, não em todo POST. Nas demais, o header é aceito e ignorado em silêncio — a requisição é processada normalmente e uma retentativa cria um segundo recurso.

Rota	Idempotente
`POST /v1/contacts`	✅
`POST /v1/deals`	✅
`POST /v1/messages/send`	✅
`POST /v1/conversations/send`	✅
Qualquer outro `POST`	❌ header ignorado
`GET`, `PATCH`, `PUT`, `DELETE`	❌ header ignorado

Como usar

Gere um UUID v4 por operação lógica e envie no header Idempotency-Key:

curl -X POST https://api.socialsell.ai/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{"name": "João Silva", "phone": "+5511999999999"}'

Na repetição, a resposta vem idêntica à original — mesmo status, mesmo corpo — acrescida de um header:

Idempotency-Replayed: true

Use Idempotency-Replayed para distinguir “criei agora” de “já existia”. Sem ele, um 201 de replay é indistinguível de um 201 de criação real.

Comportamento exato

Cenário	O que acontece
Primeira chamada, resposta `2xx`	Processa e guarda a resposta por 24 horas
Primeira chamada, resposta de erro	Processa e não guarda. A mesma chave pode ser reusada
Repetição com a mesma chave	Devolve a resposta em cache + `Idempotency-Replayed: true`
Mesma chave, corpo diferente	Devolve a resposta em cache do corpo original. O corpo novo é ignorado
Chave nova, mesmo corpo	Processa como operação independente — cria um segundo recurso
Rota não idempotente	Header ignorado

Só respostas 2xx entram no cache. Se a primeira tentativa falhou com 500, repetir com a mesma chave executa de verdade — que é o comportamento desejado numa retentativa.Não há verificação do corpo. Reutilizar uma chave com um payload diferente não gera erro: devolve silenciosamente o resultado da primeira operação. Uma chave por operação lógica, sempre.

Escopo e validade


Validade	24 horas. Depois disso a mesma chave pode ser reutilizada para uma nova operação
Escopo	Por organização — não por API Key. Duas chaves da mesma organização compartilham o mesmo espaço de idempotência

A idempotência depende do cache distribuído. Se ele estiver indisponível, a requisição é processada normalmente sem proteção contra duplicata — não há erro nem aviso na resposta. Para operações críticas, mantenha também a sua própria checagem no destino.

Exemplo — criação segura com retentativa

const { randomUUID } = require('crypto');

async function criarContatoComSeguranca(dados) {
  // A chave é gerada UMA vez, fora do laço, e reusada em toda tentativa.
  const idempotencyKey = randomUUID();

  for (let tentativa = 0; tentativa < 3; tentativa++) {
    const response = await fetch('https://api.socialsell.ai/v1/contacts', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.SOCIALSELL_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey,
      },
      body: JSON.stringify(dados),
    });

    if (response.ok) {
      const jaExistia = response.headers.get('Idempotency-Replayed') === 'true';
      return { contato: (await response.json()).data, jaExistia };
    }

    // Erro do cliente: repetir não vai ajudar
    if (response.status < 500) {
      const { error } = await response.json();
      throw new Error(`[${error.code}] ${error.message}`);
    }

    // Erro do servidor: espera e tenta de novo com a MESMA chave
    await new Promise((r) => setTimeout(r, 1000 * 2 ** tentativa));
  }

  throw new Error('Máximo de tentativas atingido');
}

Boas práticas

Gere a chave antes de enviar, não depois de falhar — uma chave criada na retentativa não protege nada.
Persista a chave junto com a operação, para reusá-la se o processo reiniciar no meio.
Uma chave por operação lógica. Nunca reaproveite entre operações diferentes: como o corpo não é verificado, o resultado seria a resposta errada, sem erro nenhum.
UUID v4. Evite chaves sequenciais ou previsíveis.
Para as rotas não idempotentes, use uma checagem própria antes de repetir — por exemplo, buscar pelo identificador externo antes de criar de novo.

Introdução

Fundamentos

Guias

Plataforma

O problema

Onde funciona

Como usar

Comportamento exato

Escopo e validade

Exemplo — criação segura com retentativa

Boas práticas

​O problema

​Onde funciona

​Como usar

​Comportamento exato

​Escopo e validade

​Exemplo — criação segura com retentativa

​Boas práticas

O problema

Onde funciona

Como usar

Comportamento exato

Escopo e validade

Exemplo — criação segura com retentativa

Boas práticas