HTTP 402 (insufficient provider balance) never reaches the terminal QUOTA failure code

[simorgh1]

Summary

A long run died on HTTP 402 (insufficient provider balance) after ~20.8M input tokens, with no deliverable and no top-up guidance. The harness already has a terminal quota failure code, but a 402 cannot reach it.

Diagnosis

httpErrorCode() in packages/llm/llm-deepseek/src/adapter.ts maps:

• 401 / 403 → AUTH
• 413 → INVALID_REQUEST
• quota-worded error body → QUOTA_EXCEEDED_CODE
• 429 → RATE_LIMIT
• 400 → context window / INVALID_REQUEST
• >= 500 → SERVER
• anything else → generic HTTP_${status}

Nothing matches status 402. Both QUOTA_EXCEEDED_CODE = 'QUOTA' and isQuotaExceededError() already exist in packages/llm/llm/src/error.ts, and the matcher does recognize "insufficient balance" wording — but only from the response body text. When the body is empty, non-JSON, or worded differently, the failure surfaces as HTTP_402, so:

• the user sees a raw transport-shaped error instead of "provider balance exhausted — top up", and
• anything keyed on the terminal QUOTA code (user messaging, failure policy, UX) never fires.

Proposed fix

Return QUOTA_EXCEEDED_CODE for status 402 ahead of the body-text check. 402 is the canonical insufficient-balance status; the status alone is sufficient evidence, and the wording check can stay as a fallback for other statuses.

Notes

• This is not a retry-storm bug. QUOTA is deliberately absent from DEFAULT_RETRYABLE_CODES in packages/llm/llm/src/retry-policy.ts, and HTTP_402 is not eligible either — so the ~20.8M tokens were spent on real work while the balance drained, and then the run ended with nothing to show.
• The larger, separate problem — no balance check before dispatching a request, and no resumable state after a refusal, which is what makes the spent tokens unrecoverable — is posted separately in Ideas: #7053 — Balance guard: refuse the next model request when the provider says is_available=false, and make an exhaustion stop resumable.

Environment

DSH 0.1.5-rc.2, DeepSeek provider, failure surfaced as HTTP 402; ending account balance −$0.24.

[argszero]

Verified this against master (ddefc45fbc), and there is one fact that makes the fix stronger than the report claims: the sibling protocol in the same package already does it.

The gap is real. The mapping moved since you read it — it now lives in packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts:97-109:

export function httpErrorCode(status: number, error?: WireError['error']): string {
  if (status === 401 || status === 403) return 'AUTH'
  if (status === 413) return 'INVALID_REQUEST'
  const detail = [error?.code, error?.type, error?.message].filter(Boolean).join(' ')
  if (isQuotaExceededError(detail)) return QUOTA_EXCEEDED_CODE
  if (status === 429) return 'RATE_LIMIT'
  if (status === 400) { ... }
  if (status >= 500) return 'SERVER'
  return `HTTP_${status}`          // ← 402 lands here
}

No status branch matches 402, so an empty or differently-worded body surfaces as HTTP_402, exactly as you describe. isQuotaExceededError (packages/llm/llm/src/error.ts:94-101) does recognize insufficient balance — its first rule is /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i — which is why the failure only shows up on the bodies that carry no text.

But look at the other protocol path in the same package — packages/llm/llm-deepseek/src/protocols/messages/transport.ts:30:

else if (isQuotaExceededError(detail) || status === 402) code = 'QUOTA'

It has had the exact rule you are proposing, for as long as the two paths have existed separately. So this is not a classification decision that needs to be made — it is an inconsistency between two code paths in one package, and the correct shape is already in the tree. That reframes the fix: it is a one-line parity change (status === 402 joined to the quota check ahead of the body-text test, as the Messages path does), with no new policy to argue about.

Worth noting in the report as well: QUOTA is deliberately absent from DEFAULT_RETRYABLE_CODES (packages/llm/llm/src/retry-policy.ts:18-24), and so is HTTP_402, so this never was a retry-storm path — which matches your own framing. What it costs is (a) the user-facing message and (b) anything keyed on the terminal QUOTA code, both of which silently never fire on the chat-completions path while working fine on the Messages path.

(I also read your companion post #7053 — the balance-gate half is separately answerable, and the agent/pre-step seam does support it; I've replied there with measurements.)