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:

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

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

In the MCP server

The MCP server’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.