Idempotência — Growth OS API

Repita a mesma escrita sem medo de duplicar — o header Idempotency-Key garante isso.

Toda rota de escrita (POST, PATCH, PUT) aceita o header Idempotency-Key. Envie o mesmo valor numa nova tentativa — timeout, queda de rede, retry automático do seu lado — e a API nunca executa a ação duas vezes.

bash

curl -X POST https://api.growthaisystem.com/api/v1/contacts \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: minha-chave-unica-123" \
  -H "Content-Type: application/json" \
  -d '{"name":"Novo contato"}'

O que volta na repetição

Mesmo corpo, mesma chave: a API devolve exatamente o resultado da primeira execução (nada roda de novo), com idempotency_replay: true somado à resposta. Numa criação, o status também muda: 201 na primeira vez, 200 nas repetições.

Corpo diferente, mesma chave: 409 idempotency_conflict — a API nunca adivinha qual das duas versões você queria, e nunca substitui a execução original silenciosamente.

Escopo da chave

Idempotency-Key é isolada por chave de API + rota — a mesma string usada em duas rotas diferentes (ou por duas chaves de API diferentes) não colide. Você não precisa incluir a rota ou o token na chave, só garantir que ela seja única por operação lógica que seu sistema está tentando fazer.