Escopo

O suporte a idempotência existe em exatamente um endpoint hoje: POST /v1/apps/{app_id}/notifications. Nenhum outro endpoint (Templates, Segments, Webhooks, Devices, Apps) lê ou respeita o header Idempotency-Key - enviá-lo em qualquer outro lugar é simplesmente ignorado.

Como funciona

Envie um header Idempotency-Key com qualquer valor único para aquele envio lógico (um UUID é um bom padrão):

curl -X POST https://your-instance/v1/apps/{app_id}/notifications \
  -H "Authorization: Bearer $REST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"target_type":"device_ids","target_value":["dev_123"],"ad_hoc_title":"Hi","ad_hoc_body":"Hello"}'

• Primeira chamada com uma determinada chave: a notificação é criada normalmente e retorna 201 Created. A chave, com escopo no App, é armazenada (Redis) junto com um hash do corpo da requisição.

• Chamada repetida com a mesma chave e o mesmo corpo: nenhuma nova notificação é criada - a notificação original é retornada, com 200 OK (não 201). É seguro repetir após um timeout ou uma conexão perdida.

• Chamada repetida com a mesma chave mas um corpo diferente: rejeitada com 409 Conflict:

  { "error": { "code": "idempotency_conflict", "message": "..." } }

  Isso pega o caso em que um cliente reutiliza uma chave por engano para um envio diferente - é tratado como um bug do chamador, não processado silenciosamente.

• Nenhum header Idempotency-Key enviado: a idempotência é ignorada por completo; toda chamada cria uma nova notificação. O header é opcional - use-o sempre que uma nova tentativa for possível (timeout de rede, resposta ambígua) e omita-o em envios genuinamente únicos que você nunca pretende repetir.

Duração da chave

Uma chave é válida por 24 horas após a primeira chamada bem-sucedida. Depois dessa janela, reutilizar o mesmo valor de chave inicia um envio totalmente novo (tratado como se a chave nunca tivesse sido usada). Não use as chaves como deduplicação de longo prazo além de um dia.

O que significa "sucesso" para o armazenamento

A chave só é marcada como usada depois que a notificação e seus registros de entrega por dispositivo são criados com sucesso. Se a requisição falhar no meio, a chave não é consumida - repetir com a mesma chave tenta uma nova criação em vez de reproduzir uma tentativa que falhou.

Orientações práticas

• Gere uma chave nova por envio lógico (por exemplo, por ação do usuário, por execução de job agendado) - nunca reutilize uma chave em envios que devem ser distintos.
• Reutilize exatamente a mesma chave apenas ao repetir uma requisição que você não tem certeza se chegou ao servidor (timeout, conexão reiniciada) - esse é o caso para o qual este recurso existe.
• Este mecanismo é específico de Notifications; ainda não existe garantia equivalente para escritas de Template, Segment ou Webhook.