> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokengift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle an empty wallet

> Turn a 402 into a funding prompt — the core loop of a user-funded app.

When a wallet can't cover a request, the API returns `402 Payment Required` with an
actionable body:

```json theme={null}
{
  "error": {
    "type": "insufficient_credits",
    "message": "このアプリのWallet残高が不足しています",
    "balance": "0.00",
    "top_up_url": "https://tokengift.ai/fuel/my-app"
  }
}
```

## The pattern

Show `top_up_url` to your user. An outage becomes a funding prompt — this is the whole
"runs while someone keeps it fueled" model:

```ts theme={null}
try {
  const res = await client.chat.completions.create({ ... });
} catch (err) {
  if (err.status === 402) {
    // 残高切れ: ユーザーにチャージページを見せる
    showBanner({
      message: "This app is out of AI fuel.",
      cta: { label: "⚡ Add fuel", href: err.error?.top_up_url },
    });
    return;
  }
  throw err;
}
```

## Watch the gauge before it hits zero

* Every response includes a `TokenGift-Balance` header — surface it in your UI.
* Subscribe to the `balance.low` [webhook](/guides/webhooks) to get notified at 20%.