---
title: Embed API Idempotency Keys
description: Retry PostNitro Embed API requests safely. Send an Idempotency-Key header and a repeated request returns the first one's result instead of creating, charging or scheduling twice.
canonical: https://postnitro.ai/docs/embed/api/idempotency
---

# Idempotency Keys

A request that times out or loses its connection may still have gone through. Retrying it
blindly can create a second post, charge credits twice, or schedule a post that publishes
twice. An `Idempotency-Key` header makes the retry safe: PostNitro remembers the first
request's result and returns it again.

```
Idempotency-Key: 8d3c6f0e-5b1a-4c2e-9f7d-2a1b3c4d5e6f
```

## Which requests take it

Every request that creates something:

| Endpoint | Creates |
| --- | --- |
| `POST /post/initiate/generate` | An AI-generated post |
| `POST /post/initiate/import` | A post from your own content |
| `POST /post/edit` | An edit of a post |
| `POST /schedule` | A scheduled post or draft |
| `POST /brand` | A brand kit |
| `POST /motion-style` | A saved motion style |
| `POST /motion-sequence` | A saved motion sequence |

The header is optional, and a request without it behaves as before. Reads, updates (`PUT`)
and deletes don't take it.

## How it works

- **Use a new key for each new action.** A UUID is ideal. A key is 1 to 255 printable ASCII
  characters with no spaces, and it belongs to your API key alone.
- **Retry with the same key and the same body.** For 24 hours after a successful request, the
  same key and body return the first response, with the same status and body, and the header
  `Idempotent-Replayed: true`. Nothing is created, charged or scheduled again.
- **Only successes are kept.** If the request failed with any `4xx` or `5xx`, nothing is
  remembered, so you can fix the request and send it again with the same key.
- **The same key with a different request** returns `422`. Bodies are compared with their keys
  sorted, so the same body serialised in another key order still matches.
- **A retry while the first request is still running** returns `409` with `Retry-After: 1`.
  Wait, then retry to get its result.

A request turned away before it runs is never remembered, whatever its key: a missing or
invalid API key (`401`), no API access (`402`), the rate limit (`429`) or a validation error.

## Example

```bash
curl --location 'https://embed-api.postnitro.ai/post/initiate/generate' \
  --header 'embed-api-key: pn-your-api-key' \
  --header 'Idempotency-Key: 8d3c6f0e-5b1a-4c2e-9f7d-2a1b3c4d5e6f' \
  --header 'Content-Type: application/json' \
  --data '{
    "postType": "CAROUSEL",
    "templateId": "your-template-id",
    "brandId": "your-brand-id",
    "presetId": "your-preset-id",
    "responseType": "PDF",
    "aiGeneration": { "type": "text", "context": "5 tips for remote work" }
  }'
```

Sending the same request again returns the same `embedPostId` instead of starting a second job.

## Error responses

| Condition | Status | Body |
| --- | --- | --- |
| Key isn't 1–255 printable characters | `400` | `{ "status": false, "message": "Idempotency-Key must be 1 to 255 printable ASCII characters, with no spaces." }` |
| Key already used for a different request | `422` | `{ "status": false, "message": "This Idempotency-Key was already used for a different request. Use a new key for a new request." }` |
| First request with this key still running | `409` | `{ "status": false, "message": "A request with this Idempotency-Key is still in progress. Retry shortly to get its result." }` |

## In the MCP server

The [MCP server](https://postnitro.ai/docs/embed/mcp)'s create tools take an optional `idempotencyKey` argument and send
it as this header. The tools that generate or import and then schedule in one call
(`postnitro_generate_and_schedule`, `postnitro_import_and_schedule`) send `<key>:create` and
`<key>:schedule`, so a retried call repeats neither step.