# Idempotency & safe retries

Retry POST /v1/posts and other writes safely with the Idempotency-Key header, plus x-request-id retry detection and the 24-hour content-hash dedup.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Send an `Idempotency-Key` header so a retried create returns the original instead of a duplicate. Timeouts and the automatic retries in n8n, Zapier and custom queues all send the same request twice.

## Retry a post create safely

Generate a UUID per logical post, keep it with the job, and send it as `Idempotency-Key` on [`POST /v1/posts`](/posts/create-post) and every retry.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import { randomUUID } from 'crypto';
import Zernio from '@zernio/node';

const zernio = new Zernio();
const idempotencyKey = randomUUID();

const { data: created } = await zernio.posts.createPost({
  headers: { 'Idempotency-Key': idempotencyKey },
  body: {
    content: 'Our January release notes are out.',
    scheduledFor: '2027-01-01T12:00:00',
    timezone: 'America/New_York',
    platforms: [{ platform: 'linkedin', accountId: '66b2e19d8c3f5a7e9d0b1c2d' }]
  }
});

const postId = created.post._id;
```
</Tab>
<Tab value="Python">
```python
import uuid
from zernio import Zernio

client = Zernio()
idempotency_key = str(uuid.uuid4())

created = client.posts.create_post(
    idempotency_key=idempotency_key,
    content="Our January release notes are out.",
    scheduled_for="2027-01-01T12:00:00",
    timezone="America/New_York",
    platforms=[{"platform": "linkedin", "accountId": "66b2e19d8c3f5a7e9d0b1c2d"}],
)

post_id = created["post"]["_id"]
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/posts" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b4986f4-77b5-4c22-a3a7-2c56f7a657e1" \
  -d '{
    "content": "Our January release notes are out.",
    "scheduledFor": "2027-01-01T12:00:00",
    "timezone": "America/New_York",
    "platforms": [{ "platform": "linkedin", "accountId": "66b2e19d8c3f5a7e9d0b1c2d" }]
  }'
```
</Tab>
</Tabs>

The first call returns `201`:

```json
{
  "message": "Post scheduled successfully",
  "post": { "_id": "65f1c0a9e2b5af0012ab34cd", "status": "scheduled", "scheduledFor": "2027-01-01T17:00:00Z" }
}
```

A retry with the same key creates nothing and returns `200` with the original post:

```json
{
  "message": "Post already exists (idempotent retry)",
  "post": { "_id": "65f1c0a9e2b5af0012ab34cd", "status": "scheduled", "scheduledFor": "2027-01-01T17:00:00Z" }
}
```

Treat that `200` as success; a new post is always `201`.

- **Key:** a fresh UUID (v4 is fine) per logical post, up to 255 characters. A longer key returns `400`.
- **Reuse** it only to retry that post after a timeout, `5xx` or connection reset. Reused on another post, the earlier post comes back instead.
- **SDKs:** the Python SDK takes `idempotency_key=`. Other SDKs pass it as a request header.

## Retry other writes safely

These also accept an optional `Idempotency-Key` (such as a UUID, up to 255 characters):

- [Send an email](/email/send-email-message), [reply](/email/reply-email-message), [forward](/email/forward-email-message), [create a draft](/email/create-email-draft) and [send a draft](/email/send-email-draft)
- [Create profile](/profiles/create-profile), [Send inbox message](/messages/send-inbox-message), [Reply to a post's comments](/comments/reply-to-inbox-post), [Reply to a review](/reviews/reply-to-inbox-review)
- [Start a WhatsApp call](/whatsapp/initiate-whatsapp-call), [Start a voice call](/voice/create-voice-call), [Send SMS](/sms/send-sms)
- [Boost a post](/ad-campaigns/boost-post), [Create an ad](/ad-campaigns/create-standalone-ad), [Create a call ad](/messaging-ads/create-call-ad)
- [Create a messaging ad](/messaging-ads/create-messaging-ad) (`POST /v1/ads/messaging`, and the legacy `POST /v1/ads/ctwa`)
- The create and duplicate endpoints for [campaigns](/ad-campaigns/create-ad-campaign), [ad sets](/ad-campaigns/create-ad-set) and ads

Send the key on the first attempt and again on the retry:

```bash
curl -i -X POST "https://zernio.com/api/v1/profiles" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f7c1f2e-6f0a-4a1f-9d2c-2b0a4f8e5c11" \
  -d '{ "name": "Acme Corp" }'
```

The retry creates nothing and replays the stored response with one extra header:

```text
HTTP/2 201
Idempotent-Replayed: true
Content-Type: application/json

{ "message": "Profile created successfully", "profile": { "_id": "66a1f0c2a4b9d3e8f1a2b3c4", "name": "Acme Corp" } }
```

- **Scope.** Keys last 24 hours, scoped to your credential and that exact path. The same key on a different `postId` returns `422` instead of replaying the other post's response.
- **Successes only.** Only a `2xx` is stored; a failure releases the key, so the retry runs for real, with one exception: for blog article creates, a `502` saying a write may have completed is stored and replayed. Check the blog, then use a new key. It covers "request succeeded, response was lost".
- **Reconcile first.** After a `5xx` or timeout the platform may have the message and the key is released. List the messages, comments or review first; empty is inconclusive.
- **Other writes** are `PUT`-style or cheap to check. When in doubt, read before you write.

## How it behaves

`POST /v1/posts` checks three layers, each over 24 hours, in this order:

1. **Same `Idempotency-Key`:** return the original post with `200` (or `409 idempotency_conflict` while it is still processing). Nothing is created.
2. **Same `x-request-id` and same content fingerprint:** return the original post with `200`.
3. **Same content fingerprint:** reject with `409` and `details.existingPostId`.
4. Otherwise, create the post.

**`Idempotency-Key` (layer 1)**

- Matches the key alone: a changed body (a re-uploaded media URL) still returns the original post.
- Covers drafts, and a post saved despite a `5xx` or timeout. If no post was created, the retry runs as new.
- Keys are scoped to your user.

**`x-request-id` (layer 2)**

- A retry only if the fingerprint matches too (same account, content and media URLs): `200` with the original in `post` instead of a duplicate-content `409`, or `202` with `postId` while it saves.
- Different content is a new post; use `Idempotency-Key` for a changed body.
- With both headers, `Idempotency-Key` wins.
- The official SDKs send a unique `x-request-id` per call. The generated SDKs expose it: [Go](/sdks/go) `.XRequestId("<uuid>")`, [Ruby](/sdks/ruby) `x_request_id:`, [Java](/sdks/java) a `UUID` argument, [.NET](/sdks/dotnet) `Guid?`, [Python](/sdks/python), [PHP](/sdks/php) and [Rust](/sdks/rust) `x_request_id`. Elsewhere, set a unique value per call or omit it.

<Callout type="warn">
In a workflow tool, generate a fresh UUID per HTTP node, or omit the header. Never reuse one execution-level `x-request-id` or `Idempotency-Key` across several nodes.
</Callout>

One value shared by 6 platform calls makes each later call a retry of the first: with `Idempotency-Key`, nothing else is created.

**Content hash (layer 3)**

- Whatever the headers, a match on `(platform, accountId, content + media URLs)` returns `409`.
- Only scheduled, publishing or published content counts, not failed or cancelled targets.
- To repost identical content within 24 hours, change the caption, the media or the account.

A `429` is also safe to retry after waiting `Retry-After` seconds ([rate limits](/guides/rate-limits)).

## If it fails

| Error | Cause | Fix |
|---|---|---|
| `409` on `POST /v1/posts` with `details.existingPostId` | This content went to this account in the last 24 hours. | Read it with [`GET /v1/posts/{postId}`](/posts/get-post); treat as success or show the user. In a retry loop, reuse one `Idempotency-Key` per post (Layer 1). |
| `409` with `code: "idempotency_conflict"` and `Retry-After` | The first request with that key is still processing. | Wait `Retry-After` seconds and resend the same request to get the original post. |
| `422` on another write endpoint | Same key with a different body, or on a different path. | Use a new key for a new request. |
| `409` on another write endpoint | The key's first request is still processing. | Retry after it completes. |
| `400` | Key over 255 characters. | Use a UUID. |

The duplicate-content `409` body:

```json
{
  "error": "This exact content is already scheduled, publishing, or was posted to this account within the last 24 hours.",
  "details": {
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "platform": "linkedin",
    "existingPostId": "65f1c0a9e2b5af0012ab34cd"
  }
}
```

## Related

- [Create post](/posts/create-post): the full idempotency contract on the operation.
- [Error handling](/guides/error-handling): the error envelope and which statuses to retry.
- [Rate limits](/guides/rate-limits): `429` and `Retry-After`.
- [Multi-tenant publishing](/multi-tenant/publishing): one key per customer request.