Every failure has a code.
Every failed Publishly post carries one of these codes — this is the engine’s actual catalog, rendered from the same module the publishing service uses. It cannot drift from what the API returns.
Every failed Publishly post carries one of 20 documented failure codes, each classed one of three ways: temporary failures retry automatically after a safe delay, needs-your-action failures wait for you to fix the connection or account, and content problems need the post itself changed. Each failure also fires a signed post.failure webhook carrying the code.
Recovers on its own.
Temporary platform problems. Publishly waits and retries these automatically — usually you do nothing. 7 of 20 codes
- queue_unavailable
- Publishly could not place this post on the delivery queue. The post can be retried safely.
- rate_limited
- The platform rate limit prevented this attempt. Publishly can retry the post safely after the limit resets.
- provider_unavailable
- The platform is temporarily unavailable. Publishly can retry this post safely.
- network_error
- Publishly could not reach the platform before sending the post. The post can be retried safely.
- status_check_failed
- Publishly could not read the platform processing status. The read-only status check can be retried safely.
- token_refresh_required
- The connection token needs an automatic refresh before Publishly can retry this post.
- internal_error
- Publishly encountered an unexpected internal error before it could complete this post. The failure was recorded for a safe retry.
Needs your action.
The connection, account or workspace needs a fix from you before the post can be retried. 7 of 20 codes
- reconnect_required
- The social account connection is no longer authorized. Reconnect the account before retrying this post.
- permission_required
- The connected account is missing a permission required to publish this post. Reconnect it with the required permissions.
- account_disabled
- This social account connection is disabled. Enable or reconnect it before retrying the post.
- account_restricted
- The platform has restricted this account from publishing. Review the account on the platform before retrying.
- provider_configuration_required
- This platform is not fully configured in Publishly. An administrator must complete the provider configuration.
- subscription_required
- This workspace needs an active publishing plan before the post can be delivered.
- outcome_unknown
- The platform may have published this post, but Publishly could not confirm the outcome. Check the social account before retrying to avoid a duplicate post.
Content problem.
The platform rejected the content itself. Change the post — retrying it unchanged fails again. 6 of 20 codes
- invalid_media
- The platform rejected the attached media. Correct the media format or specifications before retrying.
- invalid_caption
- The platform rejected the post text. Correct the caption or content before retrying.
- content_too_long
- The post text exceeds the platform limit. Shorten it before retrying.
- invalid_settings
- One or more platform settings are invalid. Correct the post settings before retrying.
- unsupported_content
- This platform does not support the requested post or media combination. Change the content before retrying.
- provider_rejected_content
- The platform rejected this post. Review the content and platform requirements before retrying.
See how failures are handled end to end.
Codes are one layer — receipts, retries & webhooks are the rest.