Reliability and retries

Production clients should assume networks fail in ambiguous ways. A timeout does not prove that DialNexa rejected a request, and repeating a write can create a second resource or place another call.

The current v1 contract does not define a platform-wide idempotency header or one universal rate limit. Do not send an invented idempotency key or hard-code a global requests-per-minute value. Use endpoint-specific guarantees when they are published.

Retry classification

Operation class	Examples	Automatic retry
Read only	List agents, get call, list voices	Safe after network errors, `429`, and transient `5xx` responses.
State transition	Publish agent, pause workflow, resume batch	Retry only after reading the resource and confirming the transition did not happen.
Resource creation	Create agent, webhook, knowledge base, phone-number purchase	Do not retry blindly. Search or list using stable business data before creating again.
Billable external action	Create call, create batch call	Never retry blindly. A timeout can occur after the call was accepted. Reconcile with calls or your metadata first.
Destructive action	Delete agent, knowledge base, phone number, or webhook	Read the resource first and treat a later `404` as a possible completed deletion.

Timeouts

Set both a connection timeout and a total request timeout in your HTTP client. Choose values that fit your application; the public contract does not currently promise one universal server timeout. Long-running work is normally accepted synchronously and completed asynchronously, so use the returned resource ID rather than holding a connection open.

Exponential backoff with jitter

This TypeScript helper retries read-only requests and honors Retry-After when the response supplies it:

async function getWithRetry(url: string, apiKey: string, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: AbortSignal.timeout(15_000),
    });

    if (response.ok) return response.json();
    if (response.status !== 429 && response.status < 500) {
      throw new Error(`Non-retryable response: ${response.status}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : Math.min(30_000, 500 * 2 ** attempt) + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
  throw new Error("Retry budget exhausted");
}

Duplicate protection without idempotency keys

Attach your own stable correlation value in metadata when creating a call. After a timeout, list recent calls and reconcile before deciding whether to submit another call. Store the returned DialNexa ID with your correlation value as soon as a create request succeeds.

Observability checklist

Record the HTTP method, route template, status, duration, and DialNexa resource ID.
Redact API keys, webhook secrets, phone numbers, and sensitive metadata.
Keep the original error statusCode, message, and error fields.
Alert separately on authorization failures, validation drift, throttling, and transient server failures.
Prefer webhooks over aggressive call-status polling.

Errors: error envelope and remediation.
Pagination: safe list iteration.
Create Call: billable action and reconciliation guidance.
Webhooks: event delivery lifecycle.

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

Retry classification

Timeouts

Exponential backoff with jitter

Duplicate protection without idempotency keys

Observability checklist

​Retry classification

​Timeouts

​Exponential backoff with jitter

​Duplicate protection without idempotency keys

​Observability checklist

​Related pages

Retry classification

Timeouts

Exponential backoff with jitter

Duplicate protection without idempotency keys

Observability checklist

Related pages