Magic Link Not Found
magic_link_not_found401
The magic link token doesn't match any active link. Request a fresh one.
What this means
The magic link token in the request doesn't match any record we have. Either the token never existed (corruption, typo, hand-typed value), or it existed and has been cleaned up after expiration. Either way, the action is the same: request a new magic link.
When you'll see this
- The user clicked an old magic link that's been pruned from our records (we periodically clean up expired tokens).
- The token was truncated when the email client wrapped or shortened the link.
- The user typed the token by hand from a printed page or screenshot, with a transcription error.
- The token was URL-encoded and decoded incorrectly somewhere in the link-handling pipeline.
- A tool prefetched the link (some email security scanners do this), consumed it, and the actual user hit a stale token.
Learn more about how this works
Magic link tokens are short-lived random strings issued during the sign-in flow. They live in our store until they're either consumed (one-time use) or expired (15-30 minutes from creation). We periodically clean up expired tokens to keep the store small. When you submit a token we don't recognize, we return magic_link_not_found rather than disclosing whether it ever existed.
The most common gotcha: email security gateways. Tools like Microsoft Safe Links and ProofPoint URL Defense often prefetch links before the user clicks them, which can consume single-use magic links before the user ever sees them. If your users keep hitting this error and they swear they're not opening old emails, look at your email infrastructure.
Example response
{
"success": false,
"error": "magic_link_not_found",
"message": "Magic link not found or already expired.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/magic_link_not_found",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Go back to asterwise.com/signin and request a fresh magic link.
- Open the new email in a browser tab, then click the link. Avoid copy-pasting the URL — that's where transcription errors happen.
- If your email client or organization has link-prefetching protection, ask IT to allowlist Asterwise's magic-link URLs.
This is a user-facing flow, not a programmatic auth path. The right "production handling" is UI handling — show a clear message and a "send a new link" button.
Python:
Production handler
- Python
- TypeScript
import httpx
def verify_magic_link(token, base_url, headers):
response = httpx.post(
f"{base_url}/v1/auth/verify",
headers=headers,
json={"token": token},
timeout=10,
)
if response.status_code == 401:
body = response.json()
if body.get("error") == "magic_link_not_found":
return {
"ok": False,
"user_message": (
"This sign-in link isn't valid. "
"Request a fresh one to continue."
),
}
response.raise_for_status()
return {"ok": True, "data": response.json()}
async function verifyMagicLink(
token: string,
baseUrl: string,
headers: HeadersInit,
) {
const response = await fetch(`${baseUrl}/v1/auth/verify`, {
method: "POST",
headers,
body: JSON.stringify({ token }),
});
if (response.status === 401) {
const body = await response.json();
if (body.error === "magic_link_not_found") {
return {
ok: false,
userMessage:
"This sign-in link isn't valid. " +
"Request a fresh one to continue.",
};
}
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return { ok: true, data: await response.json() };
}
Avoid this error by
- Don't manually edit or truncate magic-link URLs. Let users click the link as-is.
- If you control the email template, keep the link as a single unbroken token in the URL — don't insert line breaks or surrounding markup that some clients might break.
- For org email environments with aggressive link scanning, request allowlisting for Asterwise's magic-link domain.
- Always include a "request a new link" button on the sign-in failure screen. Most users hit this once, retry, and succeed.