Idempotency
Prevent duplicate alerts with idempotency keys.
Why idempotency matters
Network requests can fail in ambiguous ways. When a request times out, you don't know if it succeeded or failed. Retrying might send the same alert twice.
Idempotency keys solve this by letting Talarius recognize duplicate requests. If you send the same key twice, the second request returns the original alert ID instead of creating a duplicate.
How it works
Send with key
Include an Idempotency-Key header with your request.
Talarius stores it
Talarius remembers the key and its result for 24 hours.
Duplicates blocked
Same key = same response. No duplicate alert sent.
Usage
Add the Idempotency-Key header to your alert requests:
curl -X POST https://v1.talarius.io/alerts \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: error-db-connection-1704067200" \
-d '{"title": "Database Connection Failed", "priority": "high"}'Responses
{
"accepted": true,
"alertId": "alert_abc123...",
"queued": true
}{
"accepted": true,
"alertId": "alert_abc123...",
"duplicate": true
}Choosing idempotency keys
The key should uniquely identify the event you're alerting about. Here are some strategies:
UUID per request
Generate a UUID before the first attempt and reuse it for retries. Good for generic retry logic.
550e8400-e29b-41d4-a716-446655440000Deterministic from event data
Combine error type + timestamp. Prevents duplicates even without tracking the UUID.
db-connection-error-1704067200Hash of alert content
Hash the title + body to deduplicate identical alerts automatically.
sha256-a1b2c3d4e5f6...Code examples
JavaScript with retry
async function sendAlert(title, body, priority = 'normal') {
const idempotencyKey = crypto.randomUUID();
for (let attempt = 0; attempt < 3; attempt++) {
try {
const response = await fetch('https://v1.talarius.io/alerts', {
method: 'POST',
headers: {
'X-API-Key': process.env.TALARIUS_API_KEY,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify({ title, body, priority }),
});
if (response.ok) {
return await response.json();
}
} catch (error) {
if (attempt === 2) throw error;
await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
}
}
}Deterministic key for errors
function getErrorIdempotencyKey(error) {
// Round timestamp to nearest minute to dedupe rapid errors
const timestamp = Math.floor(Date.now() / 60000) * 60000;
return `error-${error.name}-${timestamp}`;
}
// Usage
const key = getErrorIdempotencyKey(error);
// Result: "error-TypeError-1704067200000"Best practices
Don't reuse keys for different alerts
Each unique event should have a unique key. Reusing keys will block legitimate alerts.
Keys expire after 24 hours
After 24 hours, the same key can be used again. This prevents permanent blocking.
Generate the key before retrying
Create the idempotency key once, then use it for all retry attempts of the same request.