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

# Retries and idempotency

> Understand duplicate telemetry, request retries, and the limits of ingestion acknowledgments.

Sentrial deduplicates repeated OTLP spans using their trace and span identities
within the resolved session. A retry must preserve those identities. Recording a
new tool attempt should use a new span identity so the attempt remains visible.

## Retrying a telemetry request

The current SDK sends telemetry to `POST /api/otel/v1/traces`. The TypeScript 0.6.0
transport serializes a request once and reuses that body for its bounded HTTP
retries. Re-delivery of the same identified spans does not insert another copy of
each event into the same session.

| What happened | What to preserve |
| - | - |
| The telemetry response was lost or timed out | The original telemetry payload, trace ID and span IDs |
| The agent actually tried a tool again | A distinct span for that attempt, its real arguments and result |
| A later tool result confirmed completion | The later evidence and its relationship to the earlier action |
| The business service timed out without a definitive result | The uncertainty; a timeout does not prove the action failed |

Prefer the SDK's built-in transport retry over calling the tracking method again
to recreate an already-recorded event. A new tracking call can generate a new
span ID. Sentrial cannot infer that two different span IDs represent the same
telemetry delivery just because their text matches.

For a custom OTLP exporter, retain valid identifiers across network retries and
keep session identity and parent relationships consistent. The database
deduplication key includes the resolved session, trace ID and span ID. It is not a
global content hash or a promise to merge different sessions.

## Re-delivery is not an event-edit API

Do not reuse a span ID to replace a previous tool result with different content.
Preserve the original result and record a distinct later result or attempt.
Re-declaring incompatible retained content references can be rejected.

Session completion is a separate supported lifecycle operation. The SDK can
repost its root span to finalize a session without inserting another root event.
This does not make arbitrary changes to previously ingested child events an
update contract.

## Legacy REST compatibility

Older SDKs can use `POST /api/sdk/sessions` and `POST /api/sdk/events` through
compatibility adapters. Those adapters generate internal trace/span identities
for each new POST. Repeating a session-create or event-append POST must not be
assumed idempotent.

In the legacy event body, caller-supplied `traceId` and `spanId` are retained as
client tracing metadata; they do not become the adapter's internal event
deduplication key. Do not depend on an `Idempotency-Key` header to change this
behavior. Use the current SDK or a correctly identified OTLP exporter for
retryable telemetry delivery.

See [Sessions Ingestion](https://www.sentrial.com/docs/api/sessions.md) and [Events Ingestion](https://www.sentrial.com/docs/api/events.md) for
the supported transports and required scopes.

## Business actions need their own guarantees

Telemetry deduplication does not prevent a tool from charging twice, creating two
tickets or submitting two claims. Your tool or business service must provide its
own idempotency mechanism and authoritative receipt.

Keep that business action identifier alongside the trace evidence. A trace ID
identifies execution, and a span ID identifies a recorded operation; neither is a
substitute for a downstream service's idempotency key or completion receipt.

## Verify what arrived

After a completed example prints its session ID, inspect delivery with the
published CLI and an appropriately scoped workspace key:

```bash theme={null}
npx --yes --package @sentrial/sdk@0.6.0 sentrial doctor --session <session-uuid> --json
```

Inspect reported delivery gaps and warnings, and compare the recorded tool
arguments, results and attempts with the source run. Follow pagination when
reading events. An acknowledgment or a successful Doctor check does not establish
signal accuracy or prove that the business action completed.

The [CLI reference](https://www.sentrial.com/docs/cli.md#doctor) describes read scopes and diagnostic outcomes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.