Skip to content
WhatsTIG
Get started

Idempotency

Networks fail. If a POST times out you cannot know whether the server processed it. Send an Idempotency-Key header and simply retry with the same key and body: WhatsTIG performs the action at most once and returns the original response to every retry.

POST /v1/messages
Idempotency-Key: notification-987
EndpointIdempotency-Key
POST /v1/messagesRequired
POST /v1/instancesOptional, recommended
Other endpointsNot supported (reads are naturally safe; state-changing actions such as connect or logout are idempotent by design)

Rules

  • Keys are 1–255 printable ASCII characters without spaces, scoped to the project. Use a value derived from your own data (attendance-987, invoice-2024-551-reminder-1), so a retry from another process uses the same key.
  • A replayed response has the same status and body as the original and the header Idempotent-Replayed: true.
  • The same key with a different body or endpoint returns 409 IDEMPOTENCY_KEY_REUSED.
  • Two concurrent requests with the same key: the second waits for the first and then receives the replay (or 409 IDEMPOTENCY_REQUEST_IN_PROGRESS in rare cases; retry after a moment).
  • Keys are remembered for 24 hours. If the original request failed (any error), nothing is stored and the key can be used again.
  • For messages, the key is also stored on the message itself and stays reserved for as long as the message exists: reusing it after the 24-hour replay window returns 409 IDEMPOTENCY_KEY_REUSED with details.messageId, never a second message.

How it works

The idempotency record and the business writes (message, status event, outbox event, usage) are written in one database transaction. Either everything is committed and the response is recorded, or nothing is. A concurrent request with the same key blocks on the key's primary-key lock until the first transaction finishes.

SDKs

Both SDKs send an Idempotency-Key on every message send (generated if you do not pass one) and only retry requests that are safe to retry (reads and keyed writes). Pass your own stable key when the retry might happen in a different process or after a restart.