---
title: "Message lifecycle and idempotency"
description: "Delivery status lifecycle, retry boundaries, and idempotency patterns for reliable messaging."
---

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

# Message lifecycle and idempotency

Use this guide to build retry-safe integrations.

## Message lifecycle

Typical state flow:

```text
queued -> sent -> delivered -> read
   \-> failed
```

- `queued`: accepted and waiting for dispatch.
- `sent`: handed off to provider.
- `delivered`: delivered to recipient device/provider state.
- `read`: read receipt observed.
- `failed`: dispatch failed or provider rejected.

## Retry boundaries

1. Retry on `429` and `5xx` only.
2. Do not retry validation failures (`400`, `422`) before fixing payload.
3. Use bounded exponential backoff with jitter.

## Client idempotency pattern

- Generate an operation key in your app per send intent.
- Save `operation_key -> message_id` mapping.
- If the same operation is retried, return existing `message_id` from your store.

## Webhook deduplication pattern

Use the delivery id from webhook headers (`svix-id` or `webhook-id`) to avoid duplicate processing:

```text
if delivery_id already processed:
  return 200
store delivery_id
enqueue processing
return 200
```

For `message.new` / `message.status_update`, also key business logic on `message_id` inside the JSON body.

## Reconciliation flow

1. **Send message request**

   Call `POST /v1/messages` and persist request metadata.

2. **Track status**

   Query `GET /v1/messages/{messageID}` or consume webhook events.

3. **Resolve final state**

   Treat `read` and `failed` as terminal states for most workflows.

:::info
Server-side webhook processing is designed for idempotent ingestion. Your consumer should still deduplicate events in your own storage.
:::

## Related pages

- [Send a message](/api-reference/messages/send-a-message)
- [Webhooks](/api/webhooks)

Source: https://docs.wazapin.id/api/message-lifecycle-idempotency/index.mdx