Request idempotency allows you to safely retry API requests without worrying about duplicate operations. When you include an Idempotency-Key header with your request, our API will ensure that multiple requests with the same key produce the same result.
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:
  1. First Request: The API processes your request normally and stores the response
  2. Subsequent Requests: If you retry with the same key, the API returns the stored response instead of processing the request again
  3. Automatic Cleanup: Idempotency keys expire after 24 hours
Idempotency is supported on all POST endpoints that create or modify resources:
  • API Keys: Create API keys
  • Domains: Create domains
  • Messages: Send messages and cancel scheduled messages
  • Account Members: Add team members
  • Suppressions: Create email suppressions
  • Routes: Create message routes
  • Webhooks: Create webhook endpoints
  • SMTP Credentials: Create SMTP credentials
  • Header Name: Idempotency-Key
  • Key Format: Any string up to 255 characters
  • Uniqueness: Keys are scoped to your account
  • Expiration: Keys expire after 24 hours
  • Request Method: Only POST requests support idempotency
Requests are matched based on:
  • Account ID
  • Idempotency key
  • Request body content (SHA256 hash)
  • Request path
If any of these differ, the request is treated as unique.

​
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

// Using crypto.randomUUID() (Node.js 14.17+)
const idempotencyKey = crypto.randomUUID();
// Result: "550e8400-e29b-41d4-a716-446655440000"

// Using a library like uuid
import { v4 as uuidv4 } from 'uuid';
const idempotencyKey = uuidv4();

// Custom format with timestamp
const timestamp = Date.now();
const random = Math.random().toString(36).substring(2);
const idempotencyKey = `msg_${timestamp}_${random}`;
// Result: "msg_1705317045123_k2j5h8n3m1"
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 with any POST request: 
curl -X POST https://api.ahasend.com/v2/accounts/acct_123/messages \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg_20240115_001" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome!",
    "html": "<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
Status: 200 OK (or appropriate success status)Headers:
  • Standard response headers
  • No special idempotency headers
Body: Normal response content
{
  "id": "msg_abc123",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z"
}

​
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.
const maxRetries = 3;
let attempt = 0;

while (attempt < maxRetries) {
  try {
    return await makeRequest(idempotencyKey);
  } catch (error) {
    if (error.status === 409) {
      // Request in progress, wait and retry
      await sleep(Math.pow(2, attempt) * 1000);
    } else {
      throw error;
    }
  }
  attempt++;
}

Key Expiration

Keys expire after 24 hours. Don’t reuse keys after this period as the behavior is undefined.

Error Handling

Handle different response codes appropriately:
  • 409: Wait and retry (concurrent request)
  • 412: Don’t retry (original failed)
  • 2xx with Idempotent-Replayed: true header: Success (replayed)

​
Error Scenarios

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 a moment and retry with the same key. The second request will either get a 409 again (still processing) or the final result once complete.
Response
{
  "message": "A request with this idempotency key is already in progress"
}
This happens when you retry a request whose original attempt failed.What it means: The first request with this idempotency key encountered an error and cannot be safely retried.What to do: Use a new idempotency key if you want to retry the operation.
Response
{
  "message": "The original request with this idempotency key failed and cannot be retried"
}
If you use the same idempotency key with different request data, the API will treat it as a new request.What it means: The request body, path, or other parameters don’t match the original request.What to do: Ensure you’re using the exact same request parameters when retrying, or use a different idempotency key for different requests.

​
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 body to detect changes between requests with the same idempotency key. This ensures that different requests don’t accidentally match.

​
Concurrency Protection

PostgreSQL advisory locks prevent race conditions when multiple requests with the same idempotency key arrive simultaneously. The first request proceeds normally while subsequent requests wait.

​
Storage Duration

Idempotency records are automatically cleaned up after 24 hours. This prevents the idempotency table from growing indefinitely while providing a reasonable retry window.
For high-volume applications, consider implementing client-side deduplication in addition to server-side idempotency to reduce unnecessary API calls.