Retry and Idempotency
How to make transaction ingestion safe under retries, timeouts, and transient network failures.
Section
Why idempotency matters
Financial systems retry. Networks timeout. Clients reconnect. Without idempotency, one real transaction can be submitted multiple times and create noisy or misleading downstream work.
Section
WatchTower ingestion requirement
For transaction ingestion, always send both the organization API key and an idempotency key.
Required headers
x-api-key
idempotency-key
Section
Best practice
Use a deterministic idempotency key tied to the event you are sending. Do not generate a brand-new random key every time your retry logic fires for the same event.
Good idempotency sources
- transaction ID
- source event ID
- stable upstream message ID
Section
Retry guidance
Retry on
- network timeouts
- transient 5xx responses
- upstream transport interruptions
Do not blindly retry on
- malformed payloads
- missing required fields
- authorization errors
Section
Client logging recommendation
- transaction ID
- idempotency key
- HTTP status
- response body
- timestamp
Supportability
Logging those fields for failed ingestion attempts makes reconciliation and support much easier later.
Next UpGo-Live Checklist
Continue Through The DocsWatchTower Integration Guides