Exchange Code Already Used
exchange_code_already_used401
This verification code was already consumed. Each code is single-use — request a fresh sign-in.
What this means
The exchange code in the request matches a real record, but it was already used to complete a verification step. Exchange codes are one-time tokens by design: once consumed, they can't be reused. The first verification succeeded; subsequent attempts with the same code get this error.
When you'll see this
- The user submitted the code, was verified, then submitted it again from another tab or device.
- A network retry on the client side resubmitted a code that had already succeeded.
- An automated tool or browser back-button replayed a previously-successful exchange.
- A security scanner consumed the code before the user reached the verification screen.
Learn more about how this works
Single-use is the security guarantee of exchange codes. Like magic links, allowing replay would mean a code could be used indefinitely by anyone who intercepted it. Each exchange code can be redeemed exactly once; subsequent submissions of the same code return this error.
In practice: when this error fires, the verification step the code was meant for has typically already succeeded. The user might just need to refresh and see they're already signed in.
Example response
{
"success": false,
"error": "exchange_code_already_used",
"message": "Exchange code has already been used.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/exchange_code_already_used",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Refresh the page — if the previous exchange succeeded, you're already signed in and just need to load the next screen.
- If you're definitely not signed in, request a fresh sign-in flow (new magic link or new exchange code).
- Don't retry the same code. It won't work.
Surface clearly; don't auto-retry. Check whether the user is already authenticated before showing the verification UI again.
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_already_used":
return {
"ok": False,
"user_message": (
"This verification code was already used. "
"Refresh the page — you may already be signed in. "
"If not, 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_already_used") {
return {
ok: false,
userMessage:
"This verification code was already used. " +
"Refresh the page — you may already be signed in. " +
"If not, 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
- On successful exchange, immediately advance the user out of the verification UI so they can't accidentally resubmit.
- Don't retry exchange submissions on network errors — that's the most common cause of accidental replay. Show the user a "retry?" prompt instead so they can decide.
- Disable the "submit" button on the verification form during the request to prevent double-click resubmission.
- After successful exchange, clear any client-side state holding the code so it can't be re-sent.