Home / Docs / Idempotency

Idempotency

Use the Idempotency-Key header with Postifys publishing endpoints to avoid duplicate social posts during retries, timeouts, and n8n workflow re-runs.

Last updated: 2026-08-24 · Technical source: live Postifys API behavior and API reference

Quick answer: Send a stable Idempotency-Key header on publish requests. When enforcement is enabled, the same key and same payload replays the existing post status instead of publishing again; the same key with a different payload returns 409.
Idempotency-Key: client-job-20260824-video-001

Use one unique key per intended platform destination post. Keep the key stable when retrying the same payload after a timeout, network error, or n8n workflow retry.

Supported endpoints

  • POST /api/facebook/post
  • POST /api/instagram/post
  • POST /api/youtube/post
  • POST /api/pinterest/post
  • POST /api/linkedin/post
  • POST /api/tiktok/post

Example

curl -X POST https://postifys.com/api/youtube/post \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: yt-upload-job-123" \
  -d '{
    "title": "Launch video",
    "videoUrl": "https://example.com/video.mp4",
    "channelId": "YOUTUBE_CHANNEL_ID"
  }'

Replay and conflict responses

When the key is reused with the same request payload, Postifys returns the existing post state instead of creating a second post.

{
  "success": true,
  "idempotent": true,
  "accepted": false,
  "status": "published",
  "postId": "post_abc123",
  "postSubmissionId": "post_abc123",
  "historyId": "post_abc123"
}

When the same key is reused with a different request payload, Postifys returns 409 Conflict.

{
  "success": false,
  "error": "Idempotency-Key was already used with a different request payload."
}

Safe retry practice

  1. Submit one publish request per intended destination post.
  2. Generate a stable idempotency key in your app or n8n workflow before calling Postifys.
  3. If the client times out, retry with the same key and same payload.
  4. If you intentionally change the caption, media, target account, or platform, generate a new idempotency key.
  5. Store the returned historyId beside your workflow/job record.

Why duplicates happen

  • Client retries on network timeout while the original job is already queued on a platform lane.
  • n8n workflow re-runs without checking prior node output/history id.
  • Multiple workers sharing one API key without coordination.
Mode note: Postifys can run idempotency in monitor or enforce mode. In monitor mode, keys are recorded for diagnosis. In enforce mode, duplicate same-payload requests replay the existing state and conflicting payloads return 409.

Operational notes for automation teams

Idempotency is most valuable when upstream systems retry on timeouts. Store the Postifys history ID beside every outbound job so a repeated client request can be reconciled against an existing published, failed, queued, or processing event instead of creating duplicate posts.

For n8n and custom backends, branch on the final history state and only submit a new request when the previous event is confirmed failed and the underlying media, token, or destination issue has been corrected.

Rate limits Status codes

Continue learning