gitroomhq/postiz-app · error · RefreshToken

${handleError.value}

Error message

${handleError.value}

What it means

While polling a direct-post's status, a non-zero code body is classified by handleErrors; if the classified type is 'refresh-token' a RefreshToken error is thrown so the framework refreshes the access token and retries. The message comes from handleError.value.

Source

Thrown at libraries/nestjs-libraries/src/integrations/social/tiktok.business.provider.ts:463

    } catch (err) {
      if (err instanceof RefreshToken || err instanceof Disconnect) {
        throw err;
      }

      // Transient API error while checking the status: the post may already
      // be live, so keep polling instead of failing it - if the API stays
      // broken the caller exhausts its checks and warns the user properly.
      return { status: 'pending', pendingData };
    }

    // Errors arrive as HTTP 200 with a non-zero code, invisible to this.fetch:
    // a token error must surface as RefreshToken, anything else is treated as
    // transient and keeps polling (same rationale as the catch above).
    if (post?.code !== 0) {
      const asString = JSON.stringify(post);
      const handleError = this.handleErrors(asString);
      if (handleError?.type === 'refresh-token') {
        throw new RefreshToken('tiktok-business', asString, '{}', handleError.value);
      }
      if (handleError?.type === 'disconnect') {
        throw new Disconnect('tiktok-business', asString, '{}', handleError.value);
      }
      return { status: 'pending', pendingData };
    }

    const { status, post_ids, reason } = post?.data || {};

    if (status === 'SEND_TO_USER_INBOX') {
      return {
        status: 'completed',
        releaseURL: 'https://www.tiktok.com/messages?lang=en',
        postId: 'missing',
      };
    }

    if (status === 'PUBLISH_COMPLETE') {

View on GitHub (pinned to 0f1647f749)

Solutions

  1. Let the framework handle it - RefreshToken triggers automatic refresh+retry
  2. If it persists, the refresh token itself is dead: reconnect the channel
  3. Check that refresh logic actually runs (refreshToken endpoint configured)
Defensive patterns

Strategy: retry

Type guard

const isRefreshTokenError = (e: unknown): e is RefreshToken => e instanceof Error && /token/i.test((e as any).type || '') || e instanceof RefreshToken;

Try / catch

try { await checkPost(post); } catch (e) { if (e instanceof RefreshToken) { await refreshChannelToken(e.identifier); return checkPost(post); } throw e; }

Prevention

When it happens

Trigger: The TikTok status endpoint returns an access_token expired/invalid error code, which handleErrors maps to type 'refresh-token'.

Common situations: Channel idle long enough for the access token to expire; token refreshed elsewhere causing the old one to be invalidated.

Related errors

AI-assisted analysis of gitroomhq/postiz-app@0f1647f749 (2026-08-27). Data as JSON: /api/errors/60084dfa90b1966f. Report an issue: GitHub.