Fix INSUFFICIENT_CREDITS from MCP or CLI

Inspect the exact 402 shape before choosing a recovery

Use this page when an OfflineCreator MCP or CLI workflow returns HTTP 402. Two product shapes exist and they must not be mixed. A legacy insufficient-credit response carries JSON details such as `INSUFFICIENT_CREDITS` and does not include a `PAYMENT-REQUIRED` header. An x402 challenge includes a `PAYMENT-REQUIRED` header (and typically a body `code` of `PAYMENT_REQUIRED` plus a locked quote). Preserve the status, body codes, and whether `PAYMENT-REQUIRED` was present before changing configuration.

Keep transport evidence separate from the recovery choice. The published `@offlinecreator/mcp` 0.1.2 API client preserves HTTP status and response body in `StudioApiError`, and the MCP server returns `error`, `status`, and `details`. That envelope is enough to branch: Stripe or Studio top-up for legacy 402, or the x402 wallet rail when `PAYMENT-REQUIRED` is present.

Use balance and model cost as diagnostic context

Use one read-only path for each side of the comparison. In MCP, call `get_credits`, then `list_models`. In the CLI, run `npx @offlinecreator/mcp balance`, then `npx @offlinecreator/mcp models`. Match the exact model ID from the observed workflow to the current catalog entry. Record the returned balance and displayed cost as diagnostic context. A low balance explains why a paid call was rejected or challenged; it does not by itself choose Stripe versus x402.

Do not hard-code one cost table into automation. OfflineCreator's current product page says web, MCP, CLI, and API generations share the same account credit balance and published per-model costs. On 2026-08-09, that page displayed launch costs ranging from 2 credits for FLUX Schnell to 600 credits for Veo 3.1 Fast, with other models in between. Those figures are a dated verification snapshot, not a permanent price promise. Read the live catalog before each spending decision.

MCP read path

`get_credits` → `list_models`Compare the returned balance with the selected model's current credit cost.

CLI read path

`balance` → `models`Use the JSON returned by the installed package instead of a copied price table.

Decision

Branch on the 402 shapeLegacy JSON 402 needs a human Stripe or Studio top-up; `PAYMENT-REQUIRED` needs the x402 wallet path or a deliberate Stripe fallback.

Choose Stripe handoff or x402 settlement

For an MCP caller without a configured buyer wallet, stop at diagnosis and a human purchase handoff. Published MCP tool lists do not include a card-checkout tool; agents must not invent `topup` as an MCP tool or imply that reconnecting grants credits. Humans complete Stripe Checkout or Studio pricing Buy actions in a browser.

When the server returns `PAYMENT-REQUIRED` and the stdio MCP or CLI process has `X402_EVM_PRIVATE_KEY` set, the client can settle USDC for credit packs or a locked generation quote, subject to `OFFLINECREATOR_X402_MAX_USD`. That wallet path is payment, not identity: API-key auth still runs first. Without a wallet, or when the deployment leaves x402 disabled, treat the response as the legacy insufficient-credit path and use human Stripe or Studio top-up instead.

Follow a bounded 402 recovery sequence

1. Preserve the workflow interface, package version, model ID, HTTP status, whether `PAYMENT-REQUIRED` appeared, and redacted response details. 2. Confirm the 402 came from the Studio API path. 3. Read the current balance. 4. Read the current model catalog and locate the exact model ID. 5. If `PAYMENT-REQUIRED` is present and a wallet is intentionally configured, follow the x402 settlement path documented on the agent-payments page, including the session spend cap. 6. Otherwise use a human-controlled Studio or Stripe purchase surface. On 2026-08-09 the public pricing page documented Top-ups of 1,000 and 3,000 credits with Buy actions, and stated that separately purchased top-up credits do not expire while plan credits are used first. Those figures are a dated public snapshot, not a permanent offer. 7. Read the balance again after settlement or human completion, then let the operator decide whether a retry is appropriate.

Do not create multiple checkout sessions or repeatedly submit generations merely because the symptom remains. Preserve a checkout or settlement reference without copying payment credentials, bearer tokens, API keys, wallet private keys, browser cookies, or a complete signed URL into a ticket. Escalate with timestamps, package version, model ID, displayed cost, redacted balance result, and redacted 402 body.

Distinguish four similar-looking failures

A legacy `INSUFFICIENT_CREDITS` 402 without `PAYMENT-REQUIRED` is a human funding decision. An x402 `PAYMENT-REQUIRED` challenge is a machine-payable price for the same credit ledger. A missing `get_credits` or `list_models` tool belongs in the missing-tools guide. A CLI process that prints only a message and exits nonzero may expose less structure than MCP: the published 0.1.2 entry point catches an unhandled CLI error, writes its message to stderr, and sets exit code 1.

Route an observed HTTP 429 to the dedicated rate-limit guide. Route authentication or transport symptoms to their own diagnostics. A Stripe checkout URL is only a handoff to a human browser action; receiving a URL does not prove payment completion. An x402 settlement receipt proves funds moved for that challenge, but still requires a fresh balance read before assuming the next generation will succeed.

Choose the next guide from the observed result

Stay here when the client displays HTTP 402 with insufficient-credit or payment-required details and you need a bounded recovery path. Move to the x402 agent-payments page when `PAYMENT-REQUIRED` is present and you need wallet setup or dual-rail semantics. Use the rate-limit guide for an observed HTTP 429, and return to the troubleshooting directory when the client cannot establish a healthy connection.

Canonical boundary for OfflineCreator 402 recovery

This page owns the decision path for OfflineCreator MCP or CLI workflows that return HTTP 402: distinguish legacy `INSUFFICIENT_CREDITS` from x402 `PAYMENT-REQUIRED`, read balance and model cost, then recover through human Stripe or Studio top-up, or through a configured wallet settlement path. It does not own general MCP transport failures, rate limits, or full x402 product marketing beyond the recovery branch.

The original last30days v3.18.4 run completed with the tracked plan and returned 70 items, but none were OfflineCreator-specific evidence for this symptom. Product behavior on this refresh is anchored to the public x402 agent-payments page plus immutable published package files for 0.1.1 and 0.1.2. Recheck them under the monthly freshness cadence before editorial promotion.