Exchange Code Not Found
exchange_code_not_found401
The verification code doesn't match any active exchange. Request a fresh sign-in.
What this means
The verification or exchange code in the request doesn't match any record we have. Exchange codes are short-lived tokens issued during multi-step auth flows (typically OAuth-style or numeric verification flows). When the code we receive doesn't match, either it was never valid, has been pruned after expiration, or was transcribed incorrectly.
When you'll see this
- A user mistyped a numeric verification code (digit transposition, off-by-one).
- A code was prefetched and consumed by an email or SMS security scanner before the user saw it.
- A stale code from a previous session was submitted instead of the current one.
- An automation pasted code data from the wrong source (logging output, screenshot OCR errors).
Learn more about how this works
Exchange codes live in our store from issuance until either consumption or expiry. We hash and look up incoming codes against active records; unmatched values return exchange_code_not_found. Like other auth errors, we don't disclose whether the code ever existed — the threat model includes attackers guessing at codes.
The most common gotcha: this error is distinct from exchange_code_attempt_limit_exceeded. Not-found means one wrong code. Attempt-limit means many wrong codes in succession, triggering a lockout. If you're hitting not-found repeatedly, expect attempt-limit to fire soon — the user should stop guessing and request fresh credentials.
Example response
{
"success": false,
"error": "exchange_code_not_found",
"message": "Exchange code not found or expired.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/exchange_code_not_found",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Verify the code you're submitting matches what was provided (no transcription errors).
- Start the sign-in flow fresh — request a new magic link or exchange code rather than retrying the same one.
- If the code seems correct but keeps failing, the issue is likely transcription. Copy-paste rather than typing whenever possible.
User-facing flow; surface clearly and offer to restart sign-in.
Python:
Production handler
- Python
- TypeScript
import httpx
def exchange_code(code, base_url, headers):
response = httpx.post(
f"{base_url}/v1/auth/exchange",
headers=headers,
json={"code": code},
timeout=10,
)
if response.status_code == 401:
body = response.json()
if body.get("error") == "exchange_code_not_found":
return {
"ok": False,
"user_message": (
"This verification code isn't valid. "
"Check it and try again, or request a fresh sign-in."
),
}
response.raise_for_status()
return {"ok": True, "data": response.json()}
async function exchangeCode(
code: string,
baseUrl: string,
headers: HeadersInit,
) {
const response = await fetch(`${baseUrl}/v1/auth/exchange`, {
method: "POST",
headers,
body: JSON.stringify({ code }),
});
if (response.status === 401) {
const body = await response.json();
if (body.error === "exchange_code_not_found") {
return {
ok: false,
userMessage:
"This verification code isn't valid. " +
"Check it and try again, or request a fresh sign-in.",
};
}
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return { ok: true, data: await response.json() };
}
Avoid this error by
- In your UI, validate code format (length, charset) before submission. Catching obviously-wrong codes client-side prevents wasted server attempts.
- Don't OCR codes from screenshots — transcription errors are common.
- If your UI displays codes for users to type into another device, use clearly-spaced groups (e.g.
123 456) to reduce digit-confusion errors. - After 3 failed attempts in your UI, suggest the user request a fresh code rather than continuing to guess.