HeyPuter/puter · error · HttpError

card_verification_required

card_verification_required

Error message

Please verify your card to continue

What it means

Raised by `assertVerifiedAccount` when the user row has `requires_card_verification` truthy. The account must add and verify a card before the guarded route proceeds. Like the phone branch, the `as never` cast indicates the legacy code is not yet registered in the canonical error map.

Source

Thrown at src/backend/core/http/middleware/gates.ts:386

          }
        | undefined,
): void => {
    if (user?.requires_email_confirmation && !user?.email_confirmed) {
        throw new HttpError(403, 'Please confirm your email to continue', {
            legacyCode: 'email_confirmation_required',
        });
    }
    if (user?.requires_phone_verification) {
        throw new HttpError(
            403,
            'Please verify your phone number to continue',
            {
                legacyCode: 'phone_verification_required' as never,
            },
        );
    }
    if (user?.requires_card_verification) {
        throw new HttpError(403, 'Please verify your card to continue', {
            legacyCode: 'card_verification_required' as never,
        });
    }
};

export const assertNotSuspended = (
    user: { suspended?: unknown } | undefined,
): void => {
    if (user?.suspended) {
        throw new HttpError(403, 'Account suspended', {
            legacyCode: 'forbidden',
        });
    }
};

/**
 * Reject unless the actor is acting through one of the named apps.
 * App-under-user actors are permitted iff `actor.app.uid` is in the allowList;

View on GitHub (pinned to 908ec23eda)

Solutions

  1. Complete the card verification / add-payment-method flow.
  2. As admin, clear `requires_card_verification` if the gate is misapplied.
  3. Ensure the gated feature is only reachable after the billing flow.
Defensive patterns

Strategy: try-catch

Try / catch

try { await call(); }
catch (e) {
  if (e.code === 'card_verification_required') { routeToAddPaymentMethod(); return; }
  throw e;
}

Prevention

When it happens

Trigger: An account flagged `requires_card_verification` calls any route guarded by `assertVerifiedAccount` before completing card verification.

Common situations: A billing or paid-feature gate enabled card verification for an account; the flag was set but the user hasn't added a valid payment method.

Related errors

AI-assisted analysis of HeyPuter/puter@908ec23eda (2026-08-12). Data as JSON: /api/errors/47794b13e92ffa71. Report an issue: GitHub.