Idempotency
Retry POST requests safely with the Idempotency-Key header.
Networks fail. When a POST times out you cannot tell whether CallMitra received it, and retrying blindly could create a second campaign or place a second call. Send an Idempotency-Key header and the retry returns the first result instead of doing the work twice.
curl -X POST https://api.callmitra.ai/api/v1/campaigns/create-with-leads \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Idempotency-Key: 6f1d2c4e-campaign-2026-11-15" \
-H "Content-Type: application/json" \
-d @campaign.jsonWhich endpoints support it
These POST endpoints accept Idempotency-Key. Their pages in the API reference list the header and the Idempotent-Replayed response header. On other endpoints the header is ignored.
| Resource | Endpoints |
|---|---|
| Agents | Create an agent, import an agent |
| Calls | Place a call |
| Campaigns | Create a campaign, create with leads |
| Leads | Create a lead, bulk action, add to do-not-call, add a note |
| Tickets | Create a ticket, add a note |
| Send a message | |
| Webhooks | Create an endpoint |
Rules
- Key format: any string of 1–255 characters. A UUID v4 per logical operation is a good choice. A longer or empty key is rejected with
400bad_requestandparam: "Idempotency-Key". - Scope: a key is scoped to the credential that sent it, plus the HTTP method and the exact path. Two different API keys can use the same key value without colliding. Send the credential the same way on every retry: the same API key sent once as
X-API-Keyand once asAuthorization: Bearercounts as two credentials. - Agency keys: the workspace in
X-Workspace-Idis not part of the scope. When one agency key works in several client workspaces, include the client in the key (for exampleclient-42:campaign-2026-11-15) so two clients never share a key (Agencies). - Lifetime: the result is kept for 24 hours. After that the same key starts a new request.
- Same request, same key: you get the stored status code and body again, with the header
Idempotent-Replayed: true. Successes (2xx) and client errors (4xx) are stored, except401,403,404and429. "Same request" means the same method, path and byte-for-byte body; a replay returns the stored body and content type, not the other headers of the first response. - Different body, same key:
409idempotency_key_reused. Use a new key for a new operation. - First request still running:
409idempotency_request_in_progresswithRetry-After: 1. Wait and retry with the same key. The claim is held for as long as the first request runs; if it never finishes (for example the server restarted), the claim is released after 2 minutes. - Server errors, rate limits and auth errors are not stored. If the first attempt failed with a
5xx, a429, a401, a403or a404(or the response was larger than 1 MB), the key is released and a retry runs the request again. - Large request bodies: a request body over 1 MB is processed without idempotency (the key is ignored).
- Responses that contain a secret are never stored. Create a webhook endpoint returns its signing
secretonce. A concurrent duplicate still gets409idempotency_request_in_progress, but once the first request has succeeded, a retry with the same key gets409idempotency_key_reusedinstead of the secret. Nothing is created twice: list your endpoints and rotate the secret if you lost it. - Best effort. If CallMitra's idempotency store is briefly unavailable, the request runs normally without replay protection. WhatsApp sends also keep the
Idempotency-Keyon the message permanently, so a repeated key returns the message already sent, even after 24 hours.
Retry pattern
Create the key once per operation, before the first attempt, and reuse it on every retry of that operation.
import { randomUUID } from 'node:crypto';
async function createCampaign(payload) {
const idempotencyKey = randomUUID();
for (let attempt = 0; attempt < 5; attempt++) {
try {
const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/create-with-leads', {
method: 'POST',
headers: {
'X-API-Key': process.env.CALLMITRA_API_KEY,
'Idempotency-Key': idempotencyKey,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const body = await res.json();
const inProgress = body.error?.code === 'idempotency_request_in_progress';
if (!inProgress && res.status !== 429 && res.status < 500) return body;
} catch {
// Network error or non-JSON reply: safe to retry with the same key.
}
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
}
throw new Error('Could not create the campaign');
}Only retry a 409 with the same key when its code is idempotency_request_in_progress. A 409 idempotency_key_reused means your code sent a different body under an old key; fix the bug instead of retrying.
If idempotency is unavailable
If CallMitra's idempotency store is briefly unavailable, the request still runs normally, without replay protection. Design receivers of webhooks to tolerate duplicates as well.
WhatsApp message sends (POST /whatsapp/messages) follow the same rules, and a key that already sent a message never sends a second one, even after 24 hours: the original message is returned instead. When WhatsApp is throttling or briefly unavailable the send answers 429 or 503 with Retry-After and nothing is delivered, so retrying with the same key sends the message.