Idempotency

Network calls fail halfway. Send an Idempotency-Key on POST /posts and a retry cannot double-post.

#How it works

The first request with a given key stores its response under that key. Any later request with the same key and the same body replays that stored response verbatim, without posting again.

curl -X POST "https://api.yeetpost.com/api/v2/posts" \
  -H "x-api-key: $YEETPOST_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "text": "shipped the new api docs today",
  "connectionSlugs": [
    "linkedin",
    "x"
  ]
}'

The header is optional. Without it, POST /posts behaves normally and a retry posts again.

#The three outcomes

Same key, same body: the stored response is replayed. Nothing is posted again.
Same key, different body: 409 idempotency_key_conflict. One key, one answer.
Same key while the first request is still running: also 409, so two racing retries cannot both post.

409

{
  "error": "idempotency_key_conflict",
  "message": "This Idempotency-Key was already used with a different request body."
}

409

{
  "error": "idempotency_key_conflict",
  "message": "A request with this Idempotency-Key is already in progress."
}

#Choosing a key

A key of your choosing, 1 to 255 characters, that makes this request safe to retry. A uuid per logical post works well. Reusing a key with a different body is a 409.

Keys are scoped to your account, not to a single API key, are 1 to 255 characters, and expire after 24 hours. Error responses are stored too: if the first attempt came back 400, the retry gets that same 400.

A uuid per logical post works well. So does a stable name for the thing you are announcing, such as release-v2.4.0-announcement: it makes a retry from a different process safe as well.

#Refusals that release the key

A few refusals are not settled outcomes, so the key is released instead of stored: payment_method_required, spend_cap_reached, fair_use_reached, connection_limit_exceeded, queue_empty and queue_full. A retry with the same key actually posts once you have added a card, raised your cap, passed UTC midnight, subscribed, waited for a connection to go idle, or added slots or freed one.

platform_unavailable and reconnect_required are stored like an ordinary response, so a retry with the same key replays the same refusal rather than actually resending. Fix the problem (reconnect the account, or just wait out a platform outage) and resend with a new Idempotency-Key.

#What is not idempotent

POST /posts/{postId}/publish takes the header the same way, so a retried publish of a draft cannot post it twice. Everything else does not: the one-liner POST /post/{connectionSlug} included. If you need retry safety, use POST /posts. See posting for the difference between the two.