Summary

When an LLM provider/proxy returns a 402-style billing block as a JSON payload without using the OpenAI/Anthropic-style envelope, openclaw's formatAssistantErrorText falls through every classifier and emits the raw JSON unchanged into the assistant's user-facing reply.

In production this surfaces to end users as something like:

{"error":"insufficient_balance","message":"Insufficient MBT balance. Top up or upgrade your subscription to continue.","upgradeUrl":"/settings/billing"}

…instead of the friendly billing copy that the same code path produces for OpenAI/Anthropic-shaped payloads.

Repro

Reproducible against ~/.npm-global/lib/node_modules/openclaw/dist/errors-CJULmF31.js and assistant-error-format-tQ4SCN8S.js (openclaw 2026.4.26):

const M = await import('@openclaw/.../errors-CJULmF31.js');
const formatAssistantErrorText = M.a;
const raw = '{"error":"insufficient_balance","message":"Insufficient MBT balance. Top up or upgrade your subscription to continue.","upgradeUrl":"/settings/billing"}';
const fakeMsg = { stopReason: 'error', errorMessage: raw, provider: 'google', model: 'gemini-3.1-pro-preview' };
console.log(formatAssistantErrorText(fakeMsg, { provider: 'google', model: 'gemini-3.1-pro-preview' }));
// → returns the raw JSON unchanged

Why every classifier misses it

1. isBillingErrorMessage(raw) returns false because:

   • The string "insufficient_balance" (snake-case, the value of the "error" field) is not in the billing pattern list. Lowercased, the substring "insufficient balance" (without the underscore) is in the list — but the actual rendered text in the JSON's "message" is "Insufficient MBT balance", which lowercased is "insufficient mbt balance". The "mbt" token between insufficient and balance breaks the substring match.
   • BILLING_ERROR_HEAD_RE requires the string to START with billing/credit balance/insufficient credits/payment required/http 402 — but the raw is JSON starting with {.

2. isRawApiErrorPayload(raw) returns true (it parses fine), so the function falls into formatRawAssistantErrorForUi(raw).

3. Inside formatRawAssistantErrorForUi, parseApiErrorInfo doesn't extract a usable message from this shape — it expects {"error":{"type":"…","message":"…"}} (OpenAI/Anthropic-style nested envelope) or a leading HTTP 4xx / LLM error prefix. Our shape has error as a string code at the top level, not a nested object. Result: it returns the trimmed raw payload (≤600 chars), unchanged.

End user sees the JSON.

What I'd suggest

Two small, independent fixes. Either alone would solve our case; both together close the gap permanently.

A. Recognize the snake-case top-level "error":"<code>" shape

In isRawApiErrorPayload / parseApiErrorInfo (assistant-error-format / sanitize-user-facing-text bundles), accept the shape:

{ "error": "<snake_case_code>", "message": "<human text>", "upgradeUrl"?: "..." }

When error is a string and message is a non-empty string, treat error as type and message as message. This is the Stripe-style and "PostgREST-style" error envelope — common enough to be worth handling alongside the OpenAI/Anthropic envelopes that already work.

B. Add billing-error keyword resilience

Augment the billing pattern list and/or BILLING_ERROR_HEAD_RE so that:

• The snake-case codes insufficient_balance, insufficient_credits, payment_required, quota_exceeded are recognized when they appear as a value at the top level of an error JSON (not just substring-hits in free-form prose).
• Strings of the form "insufficient <anything> balance" (where the middle token is a vendor/feature/currency word like mbt, usd, account, prepaid, etc.) are recognized. Today only the literal "insufficient balance" and "insufficient usd or diem balance" match.

Bonus: keep upgradeUrl if present

When the raw payload includes an upgradeUrl (or billing_url, manage_url, etc.), surface it in the friendly message as a clickable link. Today the URL is silently discarded.

Why we hit this

We run a transparent LLM proxy in front of multiple providers (OpenAI / Anthropic / Google). The proxy returns a uniform 402 with a JSON body that looks like the example above when a user is out of credit. Every billing-block path on every provider funnels through this format. Because the classifier doesn't recognize it, the JSON leaks to whatever surface the assistant happens to be talking to (Slack, Teams, etc.) — looks like a crash to users, not a billing message.

We have a sandbox-side workaround in flight on our end, but the right place for the friendly classification to live is in openclaw itself so every consumer benefits. Filing for upstream consideration.

Happy to send a PR for either A or B (or both) if you'd accept it. Let me know preferred shape.

Environment

• openclaw 2026.4.26
• Node v25.5.0
• Provider/model in the repro: google / gemini-3.1-pro-preview (not specific to this provider — applies to any 402 with this payload shape)