Email Delivery Failed
email_delivery_failed503
We couldn't send the email (magic link, password reset, etc.). Auth flows fall back gracefully; retry in a minute.
What this means
A request tried to trigger an outbound email — almost always a magic link for sign-in or an account-related notification — and our email provider rejected the send or timed out. The user's account, key, and session state are unchanged. Nothing was created in a half-state. The only thing that didn't happen is the email arriving in their inbox.
When you'll see this
- The user requested a magic link and our SMTP/transactional email provider is down or rate-limiting us.
- A usage warning email or invoice notification failed mid-flow (usually surfaces in background tasks, not direct API responses).
- The provider accepted the message but failed to deliver, surfaced back as a delivery exception.
- An internal queue backed up and the synchronous send timed out.
Learn more about how this works
Email delivery is the one part of any auth system that genuinely depends on third parties. Even at perfect uptime on our side, the provider can have a bad five minutes. We surface this as a clean 503 instead of pretending the email went through — that way your retry logic actually retries, and the user isn't left wondering why no link arrived.
The most common gotcha: this error means we couldn't send the email. It does not mean the email landed in spam. If the user "didn't receive" the magic link but the API returned 200, look at the user's spam folder before assuming we failed.
Example response
{
"success": false,
"error": "email_delivery_failed",
"message": "We are having trouble sending email right now. Please try again in a few minutes.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/email_delivery_failed",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Wait 60 seconds and re-trigger the email send (request another magic link, click "resend", etc.).
- If it fails twice in a row, check status.asterwise.com — we post email provider incidents there.
- If your own users are reporting that emails never arrive even on 200 responses, the issue is deliverability (spam, blocklists, corporate filters), not this error.
Treat this like any other transient 503 — short backoff, capped retries, then surface to the user with a clear "try again or use a different method" message.
Python:
Production handler
- Python
- TypeScript
import httpx
import time
def request_magic_link(email, base_url, headers):
payload = {"email": email}
for attempt in range(3):
response = httpx.post(
f"{base_url}/v1/auth/magic-link",
headers=headers,
json=payload,
timeout=10,
)
if response.status_code == 503:
body = response.json()
if body.get("error") == "email_delivery_failed":
time.sleep(15 * (attempt + 1))
continue
return response
raise RuntimeError("Email provider unavailable. Try again later.")
async function requestMagicLink(email: string, baseUrl: string, headers: HeadersInit) {
for (let attempt = 0; attempt < 3; attempt++) {
const response = await fetch(`${baseUrl}/v1/auth/magic-link`, {
method: "POST",
headers,
body: JSON.stringify({ email }),
});
if (response.status === 503) {
const body = await response.clone().json();
if (body.error === "email_delivery_failed") {
await new Promise((r) => setTimeout(r, 15_000 * (attempt + 1)));
continue;
}
}
return response;
}
throw new Error("Email provider unavailable. Try again later.");
}
Avoid this error by
- In the UI, give the user a "resend email" button rather than a "try again" generic error. The action is exactly the same; the framing tells them what to do.
- Don't loop magic link requests aggressively on your side. Magic link IP and email limits exist; retrying through this error can push the user into
magic_link_email_limit_exceeded. - For critical notifications, don't depend solely on email. Surface important account state in the UI as well so users aren't blocked by an undelivered message.