> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reliability and retries

> Build production-safe DialNexa API clients with timeouts, backoff, retry classification, and duplicate protection.

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.

<Warning>
  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.
</Warning>

## 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:

```typescript theme={null}
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.

## Related pages

* [Errors](/docs/api-reference/errors): error envelope and remediation.
* [Pagination](/docs/api-reference/pagination): safe list iteration.
* [Create Call](/docs/api-reference/v1/calls/create): billable action and reconciliation guidance.
* [Webhooks](/docs/api-reference/v1/webhooks/overview): event delivery lifecycle.