token_expired

HTTP status: N/A (SDK auth) / 401 (API)
Category: Token lifecycle

What this error means

An access token, refresh token, or ID token has expired and can no longer be used. In Customer API responses this may appear as token_inactive (401). In framework SDKs (@wocha/nextjs, @wocha/react) it appears as id_token_expired or token_refresh_failed during session handling.

Common causes

• OAuth access token past its exp claim
• Refresh token expired or revoked after logout or rotation
• ID token expired during callback validation
• Long-lived session without refresh (browser tab idle for hours)
• Clock skew between client and issuer (rare)

How to fix it

1. Customer API: Refresh the OAuth access token or create a new management API key.
2. Next.js / SvelteKit / Nuxt BFF: Ensure the refresh route is wired; the SDK refreshes automatically when configured.
3. React / Vue SPA: Call your refresh endpoint or redirect the user to sign in again.
4. ID token validation: Verify system clock; check token exp in JWT debugger.
5. Do not cache tokens beyond their lifetime; store refresh tokens securely server-side only.

Example

// Next.js — handle expired session in middleware
import { getSession } from "@wocha/nextjs/server";
 
export async function middleware(req: NextRequest) {
  try {
    const session = await getSession(req);
    if (!session) {
      return NextResponse.redirect(new URL("/login", req.url));
    }
  } catch (err) {
    if (err instanceof WochaAuthError && err.code === "token_refresh_failed") {
      return NextResponse.redirect(new URL("/login?expired=1", req.url));
    }
    throw err;
  }
}

// Customer API — OAuth bearer token expired
import { WochaAuthenticationError } from "@wocha/sdk";
 
try {
  await wocha.users.list();
} catch (err) {
  if (err instanceof WochaAuthenticationError && err.errorCode === "token_inactive") {
    const newToken = await refreshOAuthToken();
    // retry with new token
  }
}

See also

• token_refresh_failed · invalid_id_token