Idempotencia

Falhas de rede podem deixar voce sem saber se um POST deu certo. Para repetir com seguranca sem criar registros duplicados, envie o header Idempotency-Key. O Getraze armazena o resultado da primeira requisicao e o repete em qualquer retry que use a mesma chave.

A idempotencia e opt-in — requisicoes sem o header se comportam exatamente como antes.

Endpoints suportados

Metodo	Endpoint
POST	/contacts
POST	/opportunities
POST	/campaigns/:id/contacts
POST	/instagram-agents/:id/profiles

Como usar

Gere uma chave unica por operacao logica (um UUID v4 e ideal) e envie no header:

curl --request POST \
  --url "https://app.getraze.com/external/v1/contacts" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 7f1c2e9a-3b4d-4a6e-9c1f-2d3e4f5a6b7c" \
  --data '{ "name": "Jane Smith", "email": "jane@company.com" }'

Se a requisicao expirar, repita com o mesmo Idempotency-Key. A segunda chamada retorna a resposta original (com o header Idempotent-Replayed: true) em vez de criar um segundo contato.

Comportamento

Situacao	Resultado
Mesma chave, mesmo corpo, primeira chamada	Executa normalmente; a resposta 2xx e armazenada
Mesma chave, mesmo corpo, repetida	Repete a resposta armazenada (Idempotent-Replayed: true)
Mesma chave, mesmo corpo, original ainda em andamento	409 IDEMPOTENCY_CONFLICT
Mesma chave, corpo diferente	422 IDEMPOTENCY_KEY_REUSED
Primeira chamada retornou erro nao-2xx	Nao armazenada — a chave esta livre para retry

Notas

• As chaves sao isoladas por conta e armazenadas por 24 horas. Depois disso, a mesma chave e tratada como nova.
• Apenas o corpo, o metodo e o path entram na identidade da chave — parametros de query nao fazem parte.
• O Idempotency-Key deve ser uma string de 1 a 255 caracteres; caso contrario a requisicao retorna 400 VALIDATION_ERROR.
• Respostas nao-2xx intencionalmente nao sao cacheadas, entao uma falha transitoria pode ser repetida com a mesma chave.