classifyPiAiError maps textual HTTP 5xx errors ("Internal Server Error") to non-retryable PI_AI_ERROR, skipping automatic retries

[sheldonslin]

Filing a bug report here per the README ("Submit feedback or bug reports through GitHub Discussions"). It concerns the error-classification layer of packages/llm/llm-pi-ai, which degrades the retry behavior of dsh-llm-retry for transient upstream 5xx failures.

---

Summary

When an upstream gateway answers a request with HTTP 500 and a plain-text body like Internal Server Error, the failure is classified as PI_AI_ERROR instead of SERVER. Since PI_AI_ERROR is not in DEFAULT_RETRYABLE_CODES, dsh-llm-retry never retries it, and a transient 5xx that would self-heal under the SERVER code is surfaced to the user as a terminal "round failed" error banner.

Environment

• @deepseek-ai/dsh 0.1.7-rc.1
• @deepseek-ai/dsh-llm-pi-ai 0.1.7-rc.1
• @earendil-works/pi-ai 0.85.1
• Route config: custom providers entries (api: openai-completions / openai-responses) behind gateways that return bare-text 5xx bodies.

What happens

1. Upstream returns HTTP 500 with body Internal Server Error (the default Express/Koa error text; no status digits in the body).
2. The user-facing failure reads 本轮运行失败 Internal Server Error with error code PI_AI_ERROR.
3. No retry is attempted although the route's retryPolicy is mode: normal.

Root cause (three compounding steps)

1. pi-ai drops the status digits on some paths. utils/error-body.js → formatProviderError composes three display shapes. On the messageCarriesBody happy path (SDK already folded the body into error.message) it returns norm.message unchanged — e.g. the bare string Internal Server Error — without a <status>: prefix, so no 5xx digits survive into the message DSH classifies.

2. classifyPiAiError only detects 5xx by digits. In packages/llm/llm-pi-ai/lib/index.js:

   if (/\b5\d\d\b/.test(message)) return "SERVER";
   ...
   return "PI_AI_ERROR";

   A message consisting of the words Internal Server Error contains no digits, so the SERVER branch never matches and the error falls through to the PI_AI_ERROR catch-all. The same applies to Bad Gateway, Service Unavailable, Gateway Timeout, etc.

3. The catch-all code is not retryable. packages/llm/llm/lib/types/retry-policy.js:

   const DEFAULT_RETRYABLE_CODES = Object.freeze([
       EMPTY_RESPONSE_CODE, 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT',
   ]);

   PI_AI_ERROR is absent, so dsh-llm-retry (!policy.retryableCodes.includes(failure.code)) stops immediately — a transient upstream 5xx becomes a user-visible failure with zero retries.

Impact

• Transient upstream 5xx errors that the retry layer exists to absorb are surfaced as terminal round failures.
• The PI_AI_ERROR label is misleading during triage (it reads like a pi-ai internal fault while the real cause is an upstream 5xx).
• Severity: medium-low. No data loss, but the retry mechanism silently degrades on exactly the failure class it is meant to handle. Users behind unstable third-party gateways see it often.

Suggested fix (either or both)

1. In classifyPiAiError, match standard HTTP status phrases:

   if (/\b5\d\d\b|internal server error|bad gateway|service unavailable|gateway timeout/i.test(message)) return "SERVER";

   (Optionally add /\b4\d\d\b|bad request/ coverage for INVALID_REQUEST in the same style.)

2. In pi-ai's formatProviderError, keep the status digits on the messageCarriesBody path (e.g. 500: Internal Server Error) so downstream classifiers always have the numeric status available.

Optionally, consider whitelisting PI_AI_ERROR in DEFAULT_RETRYABLE_CODES — though classifying correctly (fix 1) is the more precise remedy.

Workaround (users, current version)

Add the catch-all code to the route's retryableCodes in the profile config (explicit lists replace the default, so include the defaults):

retryPolicy:
  mode: normal
  maxRetries: 5
  retryableCodes: [ EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, PI_AI_ERROR ]
  backoff: { initialDelayMs: 500, maxDelayMs: 10000, jitterRatio: 0.1 }

Evidence

• Failure banner in the running session: 本轮运行失败 Internal Server Error — code PI_AI_ERROR, message with zero digits.
• Classifier source: dsh-llm-pi-ai/lib/index.js classifyPiAiError (/\b5\d\d\b/ digit heuristic, catch-all return "PI_AI_ERROR").
• Retry whitelist source: dsh-llm/lib/types/retry-policy.js DEFAULT_RETRYABLE_CODES.
• Error text composition source: @earendil-works/pi-ai/dist/utils/error-body.js formatProviderError / messageCarriesBody.

[PerryLink]

你的诊断在代码里成立——而且你能指出确切那一行

我按你给的环境（@deepseek-ai/dsh 0.1.7-rc.1，也就是当前最新版）核对了 packages/llm/llm-pi-ai/src/stream.ts，你引的那段逐字属实：

function classifyPiAiError(message: string): string {
  ...
  if (/\b5\d\d\b/.test(message)) return 'SERVER'          // :50
  ...
  return 'PI_AI_ERROR'                                    // :67
}

• :50 只看数字：Internal Server Error、Bad Gateway、Service Unavailable、Gateway Timeout 这些标准状态短语里没有数字，于是全部落到 :67 的兜底；
• :67 的兜底不可重试：packages/llm/llm/src/retry-policy.ts 里 DEFAULT_RETRYABLE_CODES 是 [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]，不含 PI_AI_ERROR；而 packages/llm/llm-retry/src/index.ts:215 的判据正是 !policy.retryableCodes.includes(failure.code) ⇒ 直接放弃重试。

所以你描述的三步复合链条（pi-ai 丢状态数字 → 我们只按数字识别 5xx → 兜底码不在白名单）在代码上完全成立。

一条你可能没看到的旁证（对你有利）

同一个文件的 :34-41 有一条上游注记，解释为什么这里只能做文本模式匹配：

pi-ai flattens the caught error to error.message … discarding the original Error and its cause chain before it reaches us. undici carries the actionable transport detail on cause … so we are left pattern-matching terse words here.

也就是说：状态数字丢失不是我们刻意为之，而是上游把错误拍平了，我们这边只能靠字符串。这正好支持你建议 (2)（让 pi-ai 保留 <status>: 前缀）——那句话可以直接引这段注记来论证。

对你建议 (1) 的补充

你的正则 /\b5\d\d\b|internal server error|bad gateway|service unavailable|gateway timeout/i 方向正确，位置就是 stream.ts:50 这一行。要注意两点：

• 这几句都是英文标准文案；如果网关返回的是本地化文案（例如中文"服务器内部错误"），再加也不迟——但不要把匹配放宽到容易被正文误伤的词（:50 是行为分类的判据，误判成 SERVER 会让不可重试的错误被重试，方向相反的错更难查）；
• 另外 :51 已经有 timeout 分支，而 Gateway Timeout 二者都匹配——按现在的顺序会先命中 :50（SERVER）。顺序即优先级，改的时候留意这一点。

关于你的 workaround，我核了配置形状，是对的

NormalRetryPolicyConfig（packages/llm/llm/src/retry-policy.ts）的字段就是 mode / maxRetries / retryableCodes / backoff，而显式 retryableCodes 是整体替换默认集合——所以你提醒的"要把默认那五个也一起写上"是必要的，你那份 YAML 的形状没问题。

我唯一想提醒的措辞

你写"PI_AI_ERROR 标签在排查时具有误导性"——这一点我认同，而且可以加一句更精确的：它误导的方向是让人以为是 pi-ai 内部故障，而实际来源是上游 5xx。这条对 triage 的价值不比修 bug 低。

（另：你的严重性评估"medium-low、无数据丢失"我同意。补充一条影响面——任何走自定义网关、且有 5xx 返回纯文本的服务都会踩到，而这恰好是本仓推荐的自定义 provider 用法。）