Skip to content
Relay Port

Publishing

Idempotency and duplicates

The four guarantees that make retries safe, how idempotency keys behave in every case, and the 24-hour duplicate guard.

Networks fail and clients retry. Relay Port is built so that a retry does not turn into a second post. It makes four guarantees, and nothing more:

  1. One publish call per target revision. Relay Port makes the platform's publish call at most once per target revision on its own.
  2. Idempotency keys. A repeated API call with the same Idempotency-Key returns the same post.
  3. A duplicate guard. Identical content to the same account within 24 hours is refused unless you opt in.
  4. Unconfirmed, with evidence. When a platform's answer is ambiguous, the target becomes unconfirmed with the evidence attached.

In one sentence: we never send the same post twice on our own, and we tell you when a platform's response is ambiguous.

Idempotency keys

Send an Idempotency-Key header with a value of 1 to 255 characters on the requests that create something. The reference marks every operation that accepts one. Use a new value, such as a UUID, for each new request, and the same value only to repeat that request.

curl -X POST https://api.relayport.dev/posts \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: winter-menu-2026-12-01" \
  -d '{
    "mode": "schedule",
    "scheduledAt": "2026-12-01T09:00:00+09:00",
    "text": "Our winter menu is here.",
    "media": [
      { "mediaId": "0193d29f-0c4a-7e21-a5b8-2c9d8e7f6a01" },
      { "mediaId": "0193d29f-0c4a-7e22-b6c9-3d0e9f8a7b02" }
    ],
    "platformData": { "instagram": { "contentType": "carousel" } },
    "targets": [
      { "accountId": "0193c8e1-77a2-7b05-8d14-6a5b4c3d2e10" },
      { "accountId": "0193c8e1-77a2-7b06-9e25-7b6c5d4e3f21" }
    ]
  }'
Case Answer
The first request with a key It runs. A successful answer is kept for 24 hours.
The same key with the same request The kept answer again, with the header Idempotent-Replayed: true. Nothing runs twice.
The same key with different parameters 422 IdempotencyKeyReused.
The same key while the first request still runs 409 IdempotencyInProgress with Retry-After. Wait, then repeat the request with the same key.
The first request failed Nothing is kept, so the same key can run again once you fix the request.

Keys belong to the workspace, and a key used by one credential cannot be replayed by another.

The duplicate guard

If the same account received identical text and media in the last 24 hours, POST /posts answers 409 DuplicateContent. Send allowDuplicate: true when you mean to post the same content again. Together with idempotency keys, this is what makes it safe for your code, or an agent acting for you, to retry: a repeated call returns the same post or is refused.

Retrying safely

  • A network error while creating a post: send the same request again with the same Idempotency-Key.
  • A failed target: POST /posts/{id}/retry re-arms the failed targets as a new revision. A failed target never reached the platform's feed, so a retry is safe.
  • An unconfirmed target may already be live. It is retried only when you send includeUnconfirmed: true, and only after you check the account: see Unconfirmed targets.