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

# Idempotency

> Retry event requests safely: reports count each message_id once.

Network errors happen. A client cannot always know whether the collector stored a batch. ManaLens makes retries safe with the event's `message_id`.

## How it works

* Every event has a `message_id`, a UUID.
* Reports count each `message_id` once per project. So when a client sends the same event twice, page views, custom events and revenue count it once.
* The SDKs make a new `message_id` for each event, and keep it when they retry a batch.

| Endpoint | `message_id` |
| - | - |
| `POST /v0/events`, web and app events | Required |
| `POST /v0/events`, server events | Optional. The collector makes one when it is absent. |

## Retry a server event

When you send server events, set your own `message_id`, so that a retry has the same ID:

```ts theme={null}
import { randomUUID } from 'node:crypto';

const event = {
  channel: 'server',
  type: 'track',
  event: 'subscription_renewed',
  user_id: 'user_123',
  message_id: randomUUID(), // make it once, before the first try
  properties: { plan: 'pro' },
};

for (let attempt = 0; attempt < 3; attempt++) {
  const response = await fetch('https://YOUR_COLLECTOR_ENDPOINT/v0/events', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ANALYTICS_SECRET_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ events: [event] }),
  });
  if (response.status === 202) break;
  if (response.status !== 429 && response.status < 500) throw new Error(`Refused: ${response.status}`);
  const wait = Number(response.headers.get('Retry-After') || 2 ** attempt);
  await new Promise(resolve => setTimeout(resolve, wait * 1000));
}
```

To make the ID stable across process restarts, derive it from your own record. For example, store a UUID with the webhook or job that the event describes.

## Things to know

* Deduplication happens in reports, not at the collector. A repeated event can be stored twice in `raw_events`. In SQL, count events with `uniqExact(message_id)`. See [SQL access](https://docs.manalens.dev/data/catalog.md#count-correctly).
* A `message_id` must be unique in the project. Do not reuse one ID for different events.
* Retry only `429` and `5xx` responses. See [errors](https://docs.manalens.dev/api/errors.md#handle-errors-well).


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