Session Expired

Reference · Errors

session_expired401

Authentication · Affects all endpoints

This session timed out. Sign in again.

What this means

The session token in the request was valid and unused, but it's past its expiration timestamp. Sessions don't last forever — they're issued with a TTL (typically several hours to days, depending on the flow) so a leaked or stolen session has a bounded lifetime. The record still exists but the expiration time has passed.

When you'll see this

• The user left a tab open overnight and tried to act on it the next day.
• A user signed in on a public computer, walked away, and someone else opened the same tab much later.
• A session was created during a flow that expects short use (verification, exchange) and the user took longer than expected.
• An automation that uses session tokens didn't refresh before the TTL ran out.

Learn more about how this works

Every session carries an expires_at timestamp set at creation. When you submit a token, we check existence, revocation status, and expiration — failing any returns a distinct error code. Expiration is the natural-end case; revocation is the deliberate-kill case; not-found means the record is entirely gone. Same surface, different reasons.

The most common gotcha: session TTLs vary by flow. Dashboard sessions are typically longer-lived than auth-flow sessions (the short-lived sessions used during verification or OAuth handshakes). If you're hitting this error in the middle of a flow that "should be fast," check whether you're holding onto a short-TTL session past its window.

Example response

{
  "success": false,
  "error": "session_expired",
  "message": "Your session has expired. Please sign in again.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/session_expired/",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Sign in fresh at asterwise.com/signin.
2. If you were mid-flow when the session expired, restart the flow from the beginning — partial state from the expired session isn't recoverable.
3. For long-lived dashboard tabs, refresh the page periodically to keep the session token fresh.

PRODUCTION ENGINEER

Recovery pattern

Same redirect-to-signin shape. Don't auto-refresh; let the user sign in deliberately.

Python:

Production handler

Python

import httpx

def call_dashboard_endpoint(url, session_token):
    response = httpx.get(
        url,
        headers={"Authorization": f"Bearer {session_token}"},
        timeout=15,
    )
    if response.status_code == 401:
        body = response.json()
        if body.get("error") == "session_expired":
            return {"ok": False, "redirect_to": "/signin"}
    response.raise_for_status()
    return {"ok": True, "data": response.json()}

TypeScript

async function callDashboardEndpoint(url: string, sessionToken: string) {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${sessionToken}` },
  });
  if (response.status === 401) {
    const body = await response.json();
    if (body.error === "session_expired") {
      return { ok: false, redirectTo: "/signin" };
    }
  }
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return { ok: true, data: await response.json() };
}

Avoid this error by

• For long-lived dashboard use, refresh the page periodically to keep the session current.
• For automation, refresh the session token well before its TTL expires rather than waiting for the failure.
• For mid-flow expirations (sign-up, verification), complete the flow promptly. Pauses longer than a few minutes risk expiry on short-lived flow sessions.
• Don't store session tokens in long-lived storage. They're meant to be ephemeral.