Idempotency

Posting is a write operation against a third-party network. Retrying without care means double-posting. Postato solves this with an Idempotency-Key header that the platform honors end-to-end.

How it works

Send a unique Idempotency-Key per logical post:

POST /v1/workspaces/wks_01H.../posts
Authorization: Bearer smcp_...
Idempotency-Key: 8f2a4b1c-7d9e-4c3b-9a1f-5e6d8c7b4a3f
Content-Type: application/json

{ "platform": "twitter", "accountId": "acc_...", "status": "publish", ... }

• If this is the first time Postato sees the key, the post is created and enqueued.
• If the same key arrives again (a retry), Postato returns the previous response. The underlying social network is not called twice.

The queue job itself is derived as post-{postId}-{platform}, so even if something retries at the BullMQ layer the upstream network receives exactly one publish attempt.

When to generate a key

Generate one per unique user action. Common patterns:

• UUIDv4 per submit button click
• hash(userId + draftId + timestamp) for scheduled posts
• Any opaque string you can reproduce on retry

Keys are scoped to the tenant. You don't have to worry about collisions with other accounts.

Retention

Idempotency records persist long enough to cover any realistic retry window. Once past that, the key can be reused with a fresh payload. For safety, always generate a new key when the intent changes; don't reuse a key across semantically different posts.

What doesn't dedupe

Idempotency-Key dedupes at the Postato layer. If two different keys both publish the same content, you get two posts. Idempotency is about your retry safety, not content uniqueness. If you need content-level deduplication, hash the payload on your side and use that hash as the key.

Non-idempotent endpoints

Only POST /posts honors the header. GET/DELETE/PATCH endpoints don't need it; they are already safe to retry.