payg_topup_required — PAYG top-up required

The order was not created and no money was charged — instead, the server sent the price of the top-up. Body: reason: "payg_topup_required", shortfall_tokens, shortfall_lmc, shortfall_lmc_minor, quote_token, expires_at.

The order costs more than the tokens remaining in the subscription quota, but the service allows pay-as-you-go (Service.payg_access ≠ disabled). This is a payment decision point, not a key refusal and not a limit: the server is asking for consent to charge the missing part to the LMC balance.

Show the user shortfall_lmc and get explicit consent — an automatic retry here means silently charging money. The quote is short-lived (expires_at, on the order of a minute); if it has expired, a repeat request WITHOUT confirmation returns a fresh 402 with a new quote_token.

The same POST /orders with the same body plus "confirm_payg_topup": true and the "quote_token" from this response → 201, and the top-up is charged to LMC. If the price has gone up in the meantime, you get a 409 quote_mismatch. The actual split is visible in the order afterwards: tokens_from_quota and tokens_from_payg.

• quote_mismatch — quote got more expensive
• insufficient_allowance — if PAYG is disabled
• Guide: LMC, quotas, and PAYG
• POST /orders
• POST /orders/{order}/retry
• GET /subscriptions
• Wallet
• Plans