Docs › Reference › Failure classes

Failure classes: why a post failed, what to do

The five kinds of failure a result can have, the one action each offers, and which can be retried by you or by OmniPosts.

Updated

When a result for a channel does not post, it carries a failure. Every failure has one class, a stable code, a one-sentence message, one action, and a retryable flag. The app shows the message and exactly one button chosen by the action.

{
  "class": "RECONNECT",
  "code": "needs_reconnect",
  "message": "Bluesky needs you to reconnect this account before we can post.",
  "action": "RECONNECT",
  "retryable": false
}

The five classes

Class What happened Default action Retried by
RECONNECT The sign-in is dead, revoked or missing. RECONNECT Nobody. Reconnect the channel first.
RETRYABLE A temporary problem before the platform accepted the post, such as a rate limit or a refused connection. NONE_AUTO_RETRYING OmniPosts, automatically. You can retry by hand once OmniPosts has given up.
UNKNOWN Sent, but the outcome is not known, such as a timeout. VERIFY_MANUALLY Never. OmniPosts reads the post back instead.
USER_ERROR The post itself is the problem: text, media or a missing setting. FIX_CONTENT You, after you fix it.
PLATFORM_BLOCKED The platform or OmniPosts has stopped posting for this channel: a policy block, a switched-off platform, a platform OmniPosts no longer supports. CONTACT_SUPPORT Nobody.

RETRYABLE is the only class OmniPosts retries on its own. It is strictly a failure that happened before the post could have reached the platform, so a retry cannot double-post. UNKNOWN is never retried, because a retry might post twice to a real audience.

The six actions

Action Button in the app What to do
RECONNECT Reconnect platform Reconnect the channel. See Reconnect a channel.
NONE_AUTO_RETRYING None. The result says OmniPosts is trying again. Nothing. OmniPosts retries on its own. If it gives up, the action becomes RETRY.
VERIFY_MANUALLY Open platform The post may be live. Look on the platform before you do anything else. OmniPosts will not send it again.
FIX_CONTENT Edit the post Change the text, media or settings the message names, then send again.
CONTACT_SUPPORT Contact support Nothing you can fix. Write to join@omniposts.dev with the code from the result.
RETRY Try again Press Try again. The failure is safe to retry.

Which results you can retry

Try again appears only on a result that has failed and whose retryable is true. That means:

  • a RETRYABLE failure whose automatic retries are used up. Its class stays RETRYABLE and its action becomes RETRY;
  • a result that was unknown and that OmniPosts's look-up proved had not posted.

An UNKNOWN result is never retryable, and a USER_ERROR result is fixed by editing the post rather than by retrying. In the API, POST /v1/groups/{id}/retry re-queues only the failed results whose failure.retryable is true, and never one whose outcome is unconfirmed.

See also Post statuses and Posts and results.