HeyPuter/puter · error · HttpError

insufficient_funds

insufficient_funds

Error message

Insufficient credits for image generation

What it means

CloudflareImageProvider computes the generation cost from cost components and asks meteringService.hasEnoughCredits(actor, totalCostInMicroCents). If the user can't cover the cost, it throws HTTP 402 insufficient_funds before calling Cloudflare — no credits are spent. This is a pre-flight credit check.

Source

Thrown at src/backend/drivers/ai-image/providers/cloudflare/CloudflareImageProvider.ts:134

                : singleInput;
        }

        const steps = this.#resolveSteps(selectedModel, options);
        const costComponents = this.#estimateCost(selectedModel, ratio, steps, {
            hasInputImage:
                typeof options.image === 'string' &&
                options.image.trim() !== '',
        });
        const totalCostInMicroCents = costComponents.reduce(
            (acc, component) => acc + component.totalCostMicroCents,
            0,
        );
        const usageAllowed = await this.#meteringService.hasEnoughCredits(
            actor,
            totalCostInMicroCents,
        );
        if (!usageAllowed) {
            throw new HttpError(
                402,
                'Insufficient credits for image generation',
                { legacyCode: 'insufficient_funds' },
            );
        }

        const response = await this.#runModel(selectedModel, {
            ...options,
            ratio,
            steps,
        });

        this.#meteringService.batchIncrementUsages(
            actor,
            costComponents
                .filter(
                    (component) =>
                        component.usageAmount > 0 &&

View on GitHub (pinned to 908ec23eda)

Solutions

  1. Top up the user's credits / upgrade plan.
  2. Lower cost drivers (fewer steps, cheaper model) to fit within balance.
  3. Catch HTTP 402 insufficient_funds and prompt the user to add credits.

Example fix

// before
await provider.generate({ prompt, model: 'expensive-model', steps: 50 });
// after — handle insufficient funds
try { await provider.generate({ prompt }); }
catch (e) {
  if (e.code === 'insufficient_funds') { promptAddCredits(); return; }
  throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check balance if you expose metering to the caller.
const enough = await meteringService.hasEnoughCredits(actor, estimatedCostMicroCents);
if (!enough) promptAddCredits();

Try / catch

try {
  await provider.generate({ prompt });
} catch (e) {
  if (e?.code === 'insufficient_funds') { promptAddCredits(); return; }
  throw e;
}

Prevention

When it happens

Trigger: A user whose credit balance is below the computed cost of the requested Cloudflare image generation attempts to generate.

Common situations: Free-tier users out of credits; high-cost model/params that exceed remaining balance; billing/quota not topped up.

Related errors

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