Errors, rate limits and idempotency

Every error has the same shape and a machine-readable code, so a flow can branch on it without parsing English.

View as MarkdownOpenAPIBase URL https://postwire.io

Error shape

{
  "error": "not connected: tiktok. Connect it in Accounts, or post only to bluesky.",
  "code": "not_connected",
  "platforms": [
    "tiktok"
  ]
}

Result codes per network

In results[] of POST /api/post, in a scheduled post's results and in post.failed webhooks. The list is open: new codes can appear, so treat an unknown code as a failure with the text in error.

A failed network also carries what and fix: the same plain-words explanation the failure emails use.

Request rate limits

Over a limit the API answers 429 with a Retry-After header (seconds) and the same number in the body:

{
  "error": "too many requests — please slow down and retry in 60 seconds",
  "code": "rate_limited",
  "retry_after": 60
}

Plan limits (posts a month and a day, AI drafts a day and a month, brands, networks per post, the queue, media a month) are not rate limits: they answer with their own code and an upgrade link, and GET /api/usage shows each one. See plans and limits and fair use.

Network rate limits

Networks have their own limits. Telegram allows about one message a second per chat and 20 a minute in a group. PostWire spaces posts to the same chat, waits out a Telegram 429 when the request has time for it, and otherwise queues that network for right after the wait: its result is ok: true, status: "scheduled", deferred: true, code rate_limited_deferred, with the schedule_id and run_at. Nothing is lost, and the queued post is counted and sent to your webhooks when it goes out.

Idempotency: retries without duplicates

A publish cannot be undone, and n8n, Make, Zapier and agents all retry. So POST /api/post refuses the same post twice:

• Send idempotency_key (any string up to 200 characters). The same key on the same account within 24 hours answers 409 duplicate_post and publishes nothing.
• Without a key, an identical request (same networks, text, drafts, media and brand) within 2 minutes answers 409 duplicate_post.
• When nothing went out (every network failed), the lock is released at once, so the retry that fixes the problem is not refused.
• The key travels in the post.published and post.failed webhooks, so you can match events to your request.

Request

{
  "platforms": [
    "linkedin"
  ],
  "text": "Doors open at 7.",
  "idempotency_key": "order-1842-announce"
}

The same request again

{
  "error": "That idempotency_key was already used for a post on this account in the last 24 hours. Nothing was published again.",
  "code": "duplicate_post"
}