Idempotency & retries

Teler is a system of record for real-world side effects: phone calls cost money, ring real phones, and cannot be undone. Retries must be deliberate.

This page covers two retry surfaces:

• Client to Teler: when you call the API and the response is in doubt.
• Teler to your webhook endpoint: when Teler delivers an event and isn’t sure you received it.

Client → Teler

What is idempotent

Operation	Idempotent?	Why
GET reads	Yes	No state mutation.
POST /api/v1/voice/calls/initiate	No	Every call creates a new call record and dials a real phone.

Caution

Don’t blindly retry calls.create(). Each retry creates an additional call. If you retry on a network timeout where the original request actually succeeded, you’ll dial the same number twice.

Recommended retry strategy

For non-idempotent operations like calls.create():

1. Set a tight timeout on the request: 5 to 10 seconds is plenty.
2. On success, you’re done. Persist the returned call_id.
3. On a non-2xx that’s clearly a client error (400, 403, 422), don’t retry. Fix the input.
4. On a 5xx or transport failure, retry at most once, with backoff and jitter, and only if you’re confident the original request did not reach the server.
5. On uncertainty, wait for the call.initiated webhook before deciding. If it arrives within a few seconds, the call exists and you don’t need to retry.

Backoff for read operations

For idempotent GET-style operations, exponential backoff with jitter:

Attempt	Delay
1	immediate
2	1s + jitter
3	2s + jitter
4	4s + jitter
5	8s + jitter

Stop after 3 to 5 attempts. If the platform is degraded for longer, back off to a circuit-breaker rather than continuing to load it.

Python

import asyncio
import random
from teler import AsyncClient
from teler.exceptions import TelerException

async def fetch_with_retry(client, op, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            return await op()
        except TelerException as e:
            if e.code < 500 or attempt == max_attempts:
                raise
            delay = (2 ** (attempt - 1)) + random.random()
            await asyncio.sleep(delay)

Node

import { TelerException } from "@frejun/teler";

async function fetchWithRetry<T>(op: () => Promise<T>, maxAttempts = 4): Promise<T> {
    let lastError: unknown;
    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        try {
            return await op();
        } catch (err) {
            lastError = err;
            if (err instanceof TelerException && err.code < 500) throw err;
            if (attempt === maxAttempts) break;
            const delay = (2 ** (attempt - 1)) * 1000 + Math.random() * 1000;
            await new Promise((r) => setTimeout(r, delay));
        }
    }
    throw lastError;
}

Idempotent call-control mutations

While calls.create() is not idempotent, the call-control mutation endpoints are. POST /api/v1/voice/calls/{call_id}/hangup, /mute, /dtmf, and /play all require an Idempotency-Key header (up to 255 characters).

Teler fingerprints the request against that key, locks in-progress duplicates, and replays the stored response for retries (TTL ~24h). This means you can safely retry these mutations on a network timeout: reusing the same Idempotency-Key returns the original result instead of applying the action twice. See Call control for the full contract.

Teler → your webhook endpoint

Teler retries webhook delivery up to 5 times with backoff (immediate to ~30 min). See Webhooks retries for the full schedule.

This means your endpoint will receive the same event more than once under unusual conditions. Build for it.

Dedupe on receive

Every event envelope carries a unique id (an evt_<ULID>, also echoed in the X-Teler-Event-Id header). Persist an (id, processed_at) row on first receipt; reject duplicates idempotently:

Python

async def handle_webhook(event):
    if await db.events.exists(event["id"]):
        return  # already processed; idempotent ack

    await db.events.insert(event["id"])
    await process_async(event)

Node

async function handleWebhook(event: TelerEvent) {
    if (await db.events.exists(event.id)) return;
    await db.events.insert(event.id);
    await processAsync(event);
}

Note

Only the 2026-06-01 event version has a stable envelope id. If you pin the 2025-08-01 version, no id field is present — dedupe on the X-Teler-Event-Id header instead.

Stay under the 5-second timeout

Webhook handlers must return 2xx within 5 seconds. The pattern is always:

1. Verify signature
2. Check dedup table
3. Enqueue for async work
4. Return 200 OK

Doing real work inline, such as DB writes, downstream API calls, and slow integrations, pushes you past the timeout, triggers retries, and creates more duplicates.

Don’t double-record

A real-world failure mode: your handler does work + acks, but the network drops the ack. Teler retries, your dedup table catches it, but only if you inserted into the dedup table before doing the work. Otherwise the work runs twice.

Next steps

Webhooks overview The full delivery contract, retry table, and ordering rules.

Webhook signing Verify before you process: the required first step in any handler.

Errors HTTP status mapping for client errors that should not be retried.