Retry failed posts

Decide whether UniPost will retry a failed destination automatically, whether a manual retry is available, and when to wait or repair the original publish inputs first.

Automatic and manual retry are different

Read results[].retry_policy instead of inferring retry behavior from an error message. Automatic retry means UniPost already has another attempt scheduled or running. Manual retry is a caller action that is available only after the result has failed and no delivery attempt remains active.

Signal	Meaning	Your action
retry_policy.will_retry = true	An automatic retry is scheduled or running.	Wait and poll the parent post. Do not call manual retry.
retry_policy.manual_retry_allowed = true	The failed result can be submitted for a manual retry now, subject to a fresh policy and queue check.	Resolve the original blocker, then submit one manual retry.
Both are false	No automatic retry is active and manual retry is currently unavailable.	Use retry_policy.reason and the latest result fields to decide what must change.

When a failed result can be retried

Treat retry_policy.manual_retry_allowed as a best-effort snapshot. UniPost rechecks every condition when it receives the retry request, so the endpoint response is authoritative.

Check	Retry can proceed	Retry cannot proceed yet
Result state	results[].status is failed.	The result is not failed, the post already succeeded, or publishing is still processing.
Delivery job	No active job exists.	A pending, running, or retrying job already exists.
Social account	The original account is still available.	The account is disconnected or reconnect_required.
Media	The original media is still uploaded and retained.	The media was cleaned up or can no longer be resolved.
Plan and platform policy	The current plan and platform policy allow publishing.	The Free Plan TikTok restriction is active or publishing policy is unavailable.
Queue admission	The request and one new queue job are admitted.	Rate or queue-depth admission rejects the request; wait before trying again.

A result classified as non-retriable can still become manually retryable after an external condition changes. Check the current manual_retry_allowed value and fix the condition before submitting the request.

TikTok reached_active_user_cap

In Production, reached_active_user_cap is currently classified as is_retriable=false, so UniPost does not automatically retry it. This avoids repeated requests while TikTok's active-user capacity is still full.

On a Paid Plan, wait for the TikTok capacity window to recover, then call manual retry once. On the Free Plan, while the current TikTok restriction is active, UniPost returns 402 PLAN_PLATFORM_PUBLISHING_RESTRICTED and does not request TikTok. After the restriction is lifted or the workspace upgrades, a manual retry can proceed if the original media is still available.

If TikTok returns the cap again after that manual attempt, the result fails again. UniPost does not continue with another automatic retry.

Recommended retry flow

GET /v1/posts/{id} and find the destination in results[].
Confirm results[].status is failed and inspect retry_policy.manual_retry_allowed and retry_policy.reason.
Wait for the external condition to recover or reconnect the account. If the retained media is unavailable, upload it again and create a new publish request; newly uploaded media cannot be attached to the old result.
If the original media is still retained and manual retry is allowed, POST the result retry endpoint once. There is no idempotency key, so do not repeat a successful request.
Poll GET /v1/posts/{id} or your queue view until the destination reaches a terminal status.

Key responses

Status	Code	Meaning
200	queued	The retry was accepted. Poll the parent post; do not submit it again.
402	PLAN_PLATFORM_PUBLISHING_RESTRICTED	The current plan/platform publishing policy blocks this retry.
409	RESULT_NOT_RETRYABLE	The result is not currently failed.
409	QUEUE_JOB_ACTIVE	A pending, running, or retrying job already exists.
409	SOCIAL_ACCOUNT_NOT_AVAILABLE	The original connected account cannot publish right now.
409	MEDIA_REUPLOAD_REQUIRED	The retained media is no longer available.
429	RATE_LIMITED	Honor Retry-After and wait for request, enqueue, or queue-depth admission to recover.
503	POLICY_UNAVAILABLE	UniPost cannot safely evaluate the current publishing policy.