Get started

Errors & retries

Errors use plain HTTP status codes, and every error body has a stable code you can branch on.

Error shape

Branch on code; show error to people; log requestId.

Response · 422

{
  "error": "This Idempotency-Key was already used with a different request body.",
  "code": "idempotency_key_reuse",
  "requestId": "req_…"
}

Status codes

Status	Meaning
200	Success. For a synchronous publish where every network failed, the body says so per target.
201	Created — a draft, a scheduled post, or a publish that fully succeeded.
202	Accepted and queued. Read the post, or wait for a webhook, to see the result.
207	Partial: some networks published and some failed. Not an error — the successes are live.
400	The request is malformed or a field is invalid.
401	Missing, wrong, revoked or expired API key.
402	A plan limit: no active plan or trial, bulk connect outside the Unlimited plan, or X before the plan is paid.
403	The key lacks the scope, or the member lacks access to that account, group or ecosystem.
404	Not found, or not visible to this key.
409	A conflict: duplicate content within 24 hours, or the same request already in progress.
410	A headless connect token expired.
422	Validation failed, or an Idempotency-Key was reused with a different body.
429	Rate limited. Wait for the seconds in Retry-After.

Error codes

code	What to do
`unauthorized`	The key is missing or invalid.
`forbidden`	The key or member may not do this.
`rate_limited`	Over this key's read or write budget for the minute. Wait for Retry-After.
`too_many_targets`	The post has more targets than the per-post maximum (1,000 by default). Split it.
`invalid_ids`	GET /posts?ids= needs 1–100 comma-separated post UUIDs.
`validation_failed`	The post isn't valid for one or more of the selected networks — too long, wrong media, and so on.
`idempotency_key_required`	POST /posts with an API key needs an Idempotency-Key header.
`idempotency_key_reuse`	That key was used before with a different body.
`request_in_flight`	An identical request is still running. Wait, then resend to get its result.
`duplicate_content`	The same content went to the same accounts in the last 24 hours. The body includes existingPostId.
`account_not_found`	A target accountId is unknown or not available to this key.
`group_empty`	A groupId has no accounts you can publish to.
`group_forbidden`	A group is outside the ones this key or member may publish to.
`ecosystem_forbidden`	A target account is outside the ecosystems this member can access.
`scheduled_in_past`	scheduledFor is in the past.
`conflicting_schedule`	Choose one of publishNow, scheduledFor or useQueue.
`invalid_timezone`	timezone is not a valid IANA zone, such as Asia/Kolkata.
`queue_unavailable`	The queue doesn't exist, is paused, or has no free slot.
`queue_forbidden`	You can only queue into your own schedule.
`media_unreachable`	A media URL could not be fetched publicly. The body includes the url.
`media_rejected`	A media upload was refused (type or size).
`unsupported_platform`	A target is on a network that can't be published to.
`plan_required`	The plan doesn't allow it: start a trial or choose a plan in Billing, use an ecosystem (bulk connect is on Unlimited), or wait for a paid plan to connect X.

A post to several networks can succeed on some and fail on others. That is 207 (or the post.partial webhook), not a failure: the successful posts are live. Each failed target carries an error with a message, a source (user, platform or system) and a category:

category	Meaning
`auth_expired`	The account's access expired. Reconnect it; retrying won't help.
`user_content`	The network rejected the content — too long, wrong media. Fix and retry.
`platform_rejected`	The network refused for its own reasons, such as policy.
`rate_limited`	The network is throttling. Safe to retry later.
`system_error`	Something failed on our side or the network's. Safe to retry.
`unknown`	Unclassified. Check the message.

Retrying safely

Timeouts and network errors: resend POST/posts with the same Idempotency-Key and body. You get the original response back (with an Idempotent-Replayed: true header), never a second post. Keys are remembered for 24 hours.
Failed networks: call POST/posts/{id}/retry. It re-runs only the failed targets, so networks that already published are left alone.
429: wait the number of seconds in Retry-After.
auth_expired: don't retry — reconnect the account first.

Error shape

Status codes

Error codes

Partial results

Retrying safely