Fix: classify 401/403 bodies by semantics (context overflow / quota) instead of always AUTH

[exposir]

Problem

Kimi's coding API rejects an over-context request with HTTP 401:

HTTP 401
{"error":{"message":"k3-256k supports only 256K context.","type":"invalid_authentication_error"}}

Both adapters classify by HTTP status first — llm-deepseek's httpErrorCode returns AUTH for any 401/403, and llm-pi-ai's classifyPiAiError matches the 401 text — so this failure is labeled AUTH. The client's AUTH projection (which exists to protect against credential fragments in provider copy) then replaces it with the fixed copy "API key is invalid", and the real failure (context overflow) only survives in the session log. A user with a perfectly valid key ends up chasing a key problem for hours.

Fix — body semantics win over HTTP status

Three commits on exposir/deepseek-harness, branch fix/error-classify-body-semantics (clean base: upstream 47f9438):

1. fix(llm-pi-ai): classify Kimi context-limit 401 as overflow, not AUTH
   • Extends isContextWindowExceededError with capacity-claim wording ("supports only 256K context", "context window is limited to N")
   • Moves context detection ahead of the 401/403 match in classifyPiAiError
   • Extracts the provider's own message out of pi-ai's "<status>: <json body>" wrapper so the GUI shows the real sentence
2. fix(llm-deepseek): let 401/403 body name context overflow or quota
   • httpErrorCode: for 401/403, checks context-overflow and quota semantics in the parsed body before defaulting to AUTH
3. fix(llm-pi-ai): align quota precedence with llm-deepseek's httpErrorCode
   • Moves the quota check ahead of 401/403 in classifyPiAiError so both adapters share the same precedence

Resulting precedence in both adapters: body semantics (context overflow / quota) → HTTP status (401/403 → AUTH, 429 → RATE_LIMIT, …) → fallback. AUTH is the default once recognized non-auth meanings are ruled out — never an immediate return.

Behavior-change surface (deliberate, minimal)

Input	Before	After
401/403 + body naming context overflow	AUTH	CONTEXT_WINDOW_EXCEEDED
401/403 + body naming quota exhaustion	AUTH	QUOTA
401/403 + "bad key"-style body / no body	AUTH	AUTH (unchanged)
400 / 413 / 429 / 5xx mappings	unchanged	unchanged

No retry-policy impact: AUTH, QUOTA, and CONTEXT_WINDOW_EXCEEDED are all outside the default retryable set. The client's AUTH safe-projection (credential-fragment protection) is untouched.

Verification

• All existing tests pass unchanged (624 across llm, llm-deepseek, llm-pi-ai); no existing assertion was edited
• New tests cover the Kimi 401 case end-to-end, the HTTP -prefixed wrapper format, quota-on-401, and the negative cases (bare 401/403 stays AUTH, 413 stays HTTP_413)
• The over-limit 401 body above was captured from a live request against the real Kimi API

Related

Text-matching is needed because pi-ai flattens provider errors into a single errorMessage string (see the XXX(pi-ai upstream) note in llm-pi-ai/src/stream.ts). A structured {status, type, body} passthrough in pi-ai would let this classify on fields instead of text — tracked as a separate upstream item.

Branch: https://github.com/exposir/deepseek-harness/tree/fix/error-classify-body-semantics

[weijiafu14]

Supporting your "classify by semantics, not by status" proposal with a datapoint from the layer below, which shows how much of this is already solved and how much is not:

Already right at the transport layer: pi-ai's own retry classification handles the transient families correctly — fault injection into the unmodified 0.84.1 transport shows 429 (with Retry-After honored), 5xx, and connection-level errors (read tcp … connection reset) all retried and recovered; delays above the cap fail loudly rather than hanging (retry / transport).

Not covered anywhere: exactly the case you isolated — a semantically misfiled status. Kimi returning 401 for an over-context request is the same shape as the 403-quota-shown-as-invalid-key family (#1631, #3222, and #666's user hitting the same wall). Nothing below the adapter can help there: the transport sees a status, the body is the only place the truth lives, and only the adapter reads it.

So the split I'd suggest for the fix: keep status as the fallback classifier, and add body-semantic overrides for the small set of well-known lies (auth status + context/quota wording). Two properties worth building in from the start:

1. Preserve the raw provider error somewhere the user can reach — the recurring complaint in this family isn't only the wrong bucket, it's that the original message is invisible ([Bug] HTTP 403 授权拒绝被归类为 AUTH，UI 显示 "API key is invalid"，原始错误不可见 #3222 says exactly this), which sends people to rotate keys that were never broken.
2. Make the classifier's decision inspectable (log which rule fired) — otherwise the next mis-bucketed provider costs the same multi-thread archaeology this one did.