Idempotency Keys for Safe API Retries

AhaSend uses an Idempotency-Key to replay a stored result when you retry the same request. It reduces duplicate operations, but a server error, an interrupted request, or an expired record can allow the operation to run again. Reconcile uncertain sends before retrying when duplicates are unacceptable. Available on Free, Pro and Max. See plans and features.

Idempotency is particularly important for critical operations like sending emails, creating resources, or processing payments where duplicate actions could cause problems.

How It Works

When you make a request with an Idempotency-Key header:

First Request: The API processes your request normally and stores the response
Subsequent Requests: If you retry with the same key, the API returns the stored response instead of processing the request again
Server Errors Are Retriable: If the original attempt failed with a server error (HTTP 5xx) or never completed, no response is stored — retrying with the same key re-executes the request and can repeat a side effect
Automatic Cleanup: Stored idempotency responses expire after 24 hours. The exception is API key creation: because its response carries a one-time secret_key, the replayable response expires after 5 minutes

Supported Operations

Only the operations in the Supported Operations table declare the idempotency header. These cover:

API Keys: Create API keys
Domains: Create domains
Messages: Send messages
Account Members: Add team members
Suppressions: Create email suppressions
Routes: Create message routes
Webhooks: Create webhook endpoints
SMTP Credentials: Create SMTP credentials
Sub-Accounts: Create sub-accounts
Sub-Account API Keys: Create sub-account API keys

One-Time Secrets (API Key Creation)

API-key creation endpoints — Create API Key and Create Sub-Account API Key — return a one-time secret_key in the response.Their idempotent replay response is encrypted and expires after 5 minutes (instead of the usual 24 hours). Within that window, an exact retry with the same Idempotency-Key replays the same secret_key. After it, the secret can no longer be retrieved — if you lose it, create a new key.Other operations that declare idempotency store responses for 24 hours.

Key Requirements

Header Name: Idempotency-Key
Key Format: Any string up to 255 characters
Uniqueness: Keys are scoped to your account
Expiration: Stored responses expire after 24 hours — except API key creation, whose secret-bearing response expires after 5 minutes
Request Method: Only the operations listed below support idempotency; other POST operations do not gain it implicitly

Request Matching

Requests are matched based on:

Account ID
Idempotency key
Request method and path, including path parameters
Request body content (SHA256 hash)

If you reuse the same key with a different request body — or send the same body to a different endpoint or resource — the API returns 422 Unprocessable Entity.

Supported Operations

Operation
`POST /v2/accounts/{account_id}/api-keys`
`POST /v2/accounts/{account_id}/domains`
`POST /v2/accounts/{account_id}/messages`
`POST /v2/accounts/{account_id}/messages/conversation`
`POST /v2/accounts/{account_id}/members`
`POST /v2/accounts/{account_id}/sub-accounts`
`POST /v2/accounts/{account_id}/sub-accounts/{sub_account_id}/api-keys`
`POST /v2/accounts/{account_id}/suppressions`
`POST /v2/accounts/{account_id}/routes`
`POST /v2/accounts/{account_id}/webhooks`
`POST /v2/accounts/{account_id}/smtp-credentials`

A fresh execution has no Idempotent-Replayed header. A completed replay returns the original status and body with Idempotent-Replayed: true. An in-progress request returns 409, Idempotent-Replayed: false, and a positive integer Retry-After. A mismatched request returns 422 with neither of these headers. The API has no 412 failed-key response.

Key Selection Best Practices

A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are up to 255 characters long.

Key Generation Examples

import { randomUUID } from 'node:crypto';
const idempotencyKey = randomUUID();
console.log(idempotencyKey);

import uuid

# V4 UUID (recommended)
idempotency_key = str(uuid.uuid4())
# Result: "550e8400-e29b-41d4-a716-446655440000"

# Custom format with timestamp
import time
import secrets

timestamp = int(time.time())
random_suffix = secrets.token_hex(8)
idempotency_key = f"msg_{timestamp}_{random_suffix}"
# Result: "msg_1705317045_a1b2c3d4e5f6g7h8"

<?php
$idempotencyKey = bin2hex(random_bytes(32));
echo $idempotencyKey, PHP_EOL;

package main

import (
    "crypto/rand"
    "encoding/hex"
    "fmt"
)

func main() {
    key := make([]byte, 32)
    if _, err := rand.Read(key); err != nil { panic(err) }
    fmt.Println(hex.EncodeToString(key))
}

Key Collision Risk: With V4 UUIDs, the probability of generating duplicate keys is approximately 1 in 5.3 x 10^36. For practical purposes, this is negligible even at massive scale.

Usage Example

Include the Idempotency-Key header only on an operation that declares it:

curl -X POST https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg_20240115_001" \
  -d '{
    "from": {"email": "hello@yourdomain.com"},
    "recipients": [{"email": "user@example.com"}],
    "sandbox": true,
    "subject": "Welcome!",
    "html_content": "<h1>Welcome to our service!</h1>"
  }'

const response = await fetch('https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'msg_20240115_001'
  },
  body: JSON.stringify({
    from: {email: 'hello@yourdomain.com'},
    recipients: [{email: 'user@example.com'}],
    sandbox: true,
    subject: 'Welcome!',
    html_content: '<h1>Welcome to our service!</h1>'
  })
});

import requests

response = requests.post(
    'https://api.ahasend.com/v2/accounts/YOUR_ACCOUNT_ID/messages',
    headers={
        'Authorization': 'Bearer your_api_key',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'msg_20240115_001'
    },
    json={
        'from': {'email': 'hello@yourdomain.com'},
        'recipients': [{'email': 'user@example.com'}],
        'sandbox': True,
        'subject': 'Welcome!',
        'html_content': '<h1>Welcome to our service!</h1>'
    }
)

Response Behavior

The API responds differently based on the idempotency key status:

First Request
Replayed Response
Concurrent Request
Failed Original
Payload Mismatch

Status: 202 Accepted for Create Message (201 Created for resource creation)Headers:

Standard response headers
No special idempotency headers

Body: Normal response contentThe Create Message response is the per-recipient list shown in response handling.

Status: Same as original responseHeaders:

Idempotent-Replayed: true
Same content type as original

Body: Exact same response as the original requestThe Create Message response is the per-recipient list shown in response handling.

Status: 409 ConflictHeaders:

Idempotent-Replayed: false
Retry-After: <seconds> — when it is safe to retry

Body:

{
  "message": "A request with this idempotency key is already in progress"
}

Replayed: on ordinary idempotent operations, deterministic 2xx and 4xx outcomes produced after the idempotency middleware are stored and replayed. Authentication and IP allow list failures happen before that middleware and are not stored. API key creation stores a successful 201 only; a controller-produced 4xx leaves the key in progress until its lease expires.Re-executed: server errors (5xx) are transient — no response is stored, and a retry with the same idempotency key re-executes the request as if it were the first attempt.

Status: 422 Unprocessable EntityBody:

{
  "message": "idempotency key was already used with a different request payload"
}

Best Practices

Unique Keys

Use unique, descriptive keys that won’t conflict with other operations. Consider including timestamps or UUIDs.

Good: user_123_welcome_20240115_001
Bad: request_1

Retry Logic

Implement exponential backoff when retrying requests. Always use the same idempotency key for retries.Pass a makeRequest(key) callback that sends the same body each time and throws an object with HTTP status and retryAfter seconds on failure. Only use this retry policy after deciding that retrying an uncertain send is acceptable.

export async function retryInProgress(makeRequest, idempotencyKey) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await makeRequest(idempotencyKey);
    } catch (error) {
      if (error.status !== 409 || attempt === 2) throw error;
      const seconds = Number(error.retryAfter);
      const wait = Number.isFinite(seconds) && seconds > 0 ? seconds : 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    }
  }
}

Key Expiration

Stored responses expire after 24 hours — don’t reuse a key after this period, as it can execute again. API key creation is shorter: its one-time secret_key is only replayable for 5 minutes.

Error Handling

Handle different response codes appropriately:

409: Concurrent request in progress — wait for the Retry-After interval, then retry with the same key
422: Key reused with a different request — use a new idempotency key, or retry with the original payload and endpoint
5xx: Transient failure — retry with the same idempotency key
2xx/4xx with Idempotent-Replayed: true header: replayed original outcome

Error Scenarios

Request Already in Progress (409 Conflict)

This happens when you make concurrent requests with the same idempotency key.What it means: Another request with the same key is currently being processed.What to do: Wait for the interval indicated by the Retry-After response header, then retry with the same key. The retry will either get a 409 again (still processing), the stored result once complete, or — if the original request never completed (e.g. it was interrupted) — it will re-execute the request once the in-flight lease expires (at most 5 minutes).

Response

{
  "message": "A request with this idempotency key is already in progress"
}

Original Request Failed with a Server Error

If the original request failed with an HTTP 5xx error, no response is stored for the idempotency key.What it means: The failure is treated as transient, and the key remains usable.What to do: Retry with the same idempotency key — the request is re-executed as if it were the first attempt. (Ordinary operations store deterministic 4xx responses after idempotency middleware. Authentication, IP allow list failures, and the two API-key create operations have the exceptions described above.)

Key Mismatch

If you use the same idempotency key with different request data — or with the same data against a different endpoint or resource — the API returns 422 Unprocessable Entity.What it means: The request doesn’t match the original request for that key.What to do: Ensure you’re using the exact same request (payload and endpoint) when retrying, or use a different idempotency key for different requests.

Response

{
  "message": "idempotency key was already used with a different request payload"
}

Implementation Details

The following technical details are provided for transparency but are not required for basic usage.

Request Hashing

The API uses SHA256 hashing of the request method, path, and body to detect changes between requests with the same idempotency key. This ensures that different requests don’t accidentally match — including the same payload sent to a different resource.

Concurrency Protection

Claiming an idempotency key happens atomically; While a request is in flight, concurrent requests with the same key receive 409 Conflict with a Retry-After header instead of waiting.

Execution Leases

An in-flight request holds a lease on its idempotency key for up to 5 minutes. If the original request never completes (for example, it was interrupted by a deploy or crash), the key unblocks automatically when the lease expires and the next retry re-executes the request.

Storage Duration

Ordinary stored results expire after 24 hours; successful API-key creation results expire after 5 minutes. After expiry, the same key can run a new operation. Responses that contain a one-time secret — API key creation and sub-account API key creation — are stored encrypted and their replayable response expires after 5 minutes. Within that window an exact retry replays the same secret_key; afterward the secret can no longer be returned.

For high-volume applications, consider implementing client-side deduplication in addition to server-side idempotency to reduce unnecessary API calls.

Overview

API reference

Webhooks

Message Routing

API v1 (legacy)

Idempotency Keys for Safe API Retries

How It Works

Supported Operations

Key Selection Best Practices

Key Generation Examples

Usage Example

Response Behavior

Best Practices

Unique Keys

Retry Logic

Key Expiration

Error Handling

Error Scenarios

Implementation Details

Request Hashing

Concurrency Protection

Execution Leases

Storage Duration

​How It Works

​Supported Operations

​Key Selection Best Practices

​Key Generation Examples

​Usage Example

​Response Behavior

​Best Practices

Unique Keys

Retry Logic

Key Expiration

Error Handling

​Error Scenarios

​Implementation Details

​Request Hashing

​Concurrency Protection

​Execution Leases

​Storage Duration

​Related Guides

How It Works

Supported Operations

Key Selection Best Practices

Key Generation Examples

Usage Example

Response Behavior

Best Practices

Error Scenarios

Implementation Details

Request Hashing

Concurrency Protection

Execution Leases

Storage Duration

Related Guides