ZCode 报错信息 报错摘要 Captcha instance timed out after 10000ms. TraceID: e4bf003a-d06e...

🌐 错误翻译

原文：Captcha instance timed out after 10000ms.
译文：验证码实例在10000毫秒后超时。

🎯 原因分析

错误发生在当前请求的验证码验证环节，验证码实例（Captcha instance）在10秒的预设时间窗口内未得到成功响应，导致整体请求执行失败。这通常与网络延迟、服务端验证阻塞或验证码服务暂时不可用有关，reason 字段为 unknown 说明框架未能捕获具体异常类型。

💡 解决方案

// 在发起请求前，适当增加验证码服务的超时阈值，或显式处理验证码超时异常
const captchaTimeoutMs = 30000; // 将超时时间延长至 30 秒

try {
  const response = await callWithCaptcha({
    provider: 'account:zai-start-plan',
    model: 'GLM-5.3-Flash',
    timeout: captchaTimeoutMs,
    // 若需要，可在回调中刷新验证码，再次重试
    retryOnCaptchaTimeout: true,
  });
} catch (err) {
  if (err.code === 'CAPTCHA_TIMEOUT') {
    console.warn('验证码验证超时，建议刷新后重试');
  } else {
    throw err;
  }
}

🛡️ 预防措施

• 提升验证码服务可用性：确保验证码生成、校验链路使用的服务稳定，监控其响应耗时，避免在高峰期触发瓶颈。

• 增强重试与降级策略：在客户端封装验证码超时的统一处理逻辑，当超时发生时自动触发重试或验证码刷新机制，减少业务中断风险。