Anyone who automates social posting eventually meets this problem. A script sends a request to create a post. The connection is slow, the HTTP client gives up after thirty seconds, and the retry logic sends the request again. But the first request had already succeeded. Now the brand account shows the same post twice.
What an idempotency key does
An idempotency key is a value you send with a request to say “this is the same operation as before”. The GPTpost API accepts an Idempotency-Key header on create calls. If a request arrives with a key the API has already seen, it returns the result of the original request instead of creating something new.
Without the header, each request is treated as new, so a retry creates a duplicate. That is why we recommend always sending one.
Choosing good keys
- Describe the logical post, not the attempt. A key like
launch-2026-11-20-mastodonstays the same across retries. A timestamp does not. - One key per post per account, if you create separate posts per account.
- Use only safe characters. Letters, digits and a few punctuation marks such as dots, colons and hyphens.
- Never reuse a key for different content.
Combine with a local record
For longer jobs, such as scheduling a whole content calendar, keep a small local file that records which posts were created. On a re-run, the script skips what it already did, and the idempotency key covers the edge case where a request succeeded but the response was lost.
Handle rate limits politely
The API allows about 120 requests and 30 writes per minute per key. When you hit the limit, the response is a 429 with a Retry-After header. Wait that long, then retry with the same idempotency key.
We use exactly this pattern to schedule our own posts. Docs and examples: GPTpost social media API.
https://oraglegpt.org/use-cases/social-media-api/?utm_source=facebook&utm_medium=social&utm_campaign=organic90

