What causes "Checkout timed out. Please try again." in koala73/worldmonitor?

Retry the checkout after a short delay; the message explicitly invites a retry.

koala73/worldmonitor · error · ConvexError

Checkout timed out. Please try again.

Error message

Checkout timed out. Please try again.

What it means

The checkout Convex action calls _createCheckoutSession and, when the outcome indicates a timeout, throws a ConvexError with code and the user-facing message 'Checkout timed out. Please try again.'. The payment provider did not return a session within the allowed window, so the checkout is aborted with a retryable error rather than a partial session.

Solutions

Retry the checkout after a short delay; the message explicitly invites a retry.
Check the payment provider's status page for an ongoing incident.
Verify provider API keys and network egress from the Convex environment.
If timeouts persist, inspect provider latency and consider increasing the internal timeout budget or adding fallback provider config.

Example fix

// before
await ctx.runMutation(api.payments.checkout.createCheckoutSession, args); // throws on provider slowness
// after
try {
  await createCheckout(args);
} catch (e) {
  if (isCheckoutTimedOut(e)) await delay(1000), await createCheckout(args);
  else throw e;
}

Defensive patterns

Strategy: retry

Try / catch

try { await checkout(args); } catch (e) {
  const msg = e?.data?.message ?? e?.message;
  if (typeof msg === 'string' && msg.includes('Checkout timed out')) {
    await sleep(1500); return checkout(args); // bounded retries
  }
  throw e;
}

Prevention

Implement bounded retry with backoff around checkout calls
Monitor payment provider status pages and alert on incidents
Verify provider credentials and region endpoints during setup
Set client-side timeouts aligned with the backend's provider timeout

When it happens

Trigger: Invoking the checkout action when the payment provider (e.g. Stripe) is slow or unresponsive and _createCheckoutSession resolves with a timeout outcome (isCheckoutTimedOutOutcome true).

Common situations: Payment provider outage or degraded performance; network latency between the Convex backend and the provider; very high checkout traffic; stale provider API keys causing hanging requests.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of koala73/worldmonitor@e586b8b4b8 (2026-09-22). Data as JSON: /api/errors/726d1eaed93da9ba. Report an issue: GitHub.

Appendix: source

Thrown at convex/payments/checkout.ts:516

    if (blocking) {
      throw new ConvexError(buildBlockedCheckoutPayload(blocking));
    }
    if (pending) {
      throw new ConvexError(buildPendingBlockedPayload(pending));
    }

    const customerName = identity
      ? [identity.givenName, identity.familyName].filter(Boolean).join(" ") ||
        identity.name
      : undefined;

    const result = await _createCheckoutSession(ctx, args, {
      userId,
      email: identity?.email,
      name: customerName,
    });
    if (isCheckoutTimedOutOutcome(result)) {
      throw new ConvexError({
        code: result.code,
        message: "Checkout timed out. Please try again.",
      });
    }
    // The public Convex action historically rejects provider failures. Keep
    // that error-channel contract: only the trusted internal relay consumes
    // the typed outcome and translates it into HTTP 429 + Retry-After.
    if (isCheckoutRateLimitedOutcome(result)) {
      throw new ConvexError({
        code: CHECKOUT_RATE_LIMITED,
        message: "Checkout is temporarily rate limited. Retry shortly.",
        retryAfterSeconds: result.retryAfterSeconds,
      });
    }
    return result;
  },
});

View on GitHub (pinned to e586b8b4b8)