AI SDK 错误码设计给开发者一个能处理的失败一、错误不是字符串越长越好开源 AI SDK 调用模型、工具、插件和缓存时失败很常见超时、限流、鉴权失败、输出解析失败、上下文过长、供应商不可用。如果 SDK 只抛一段字符串开发者很难写恢复逻辑。好的错误码设计是给开发者一个能处理的失败。二、错误要分类flowchart TD A[SDK Error] -- B[配置错误] A -- C[网络错误] A -- D[供应商错误] A -- E[解析错误] A -- F[权限错误]每类错误要有稳定 code、message、retryable、cause 和建议动作。type SdkError { code: string; message: string; retryable: boolean; suggestion?: string; };稳定 code 比自然语言 message 更适合程序处理。三、重试语义要明确超时、502、限流可能可重试鉴权失败、参数错误、权限不足通常不应该重试。SDK 应该明确告诉调用方。retry_policy: timeout: retryable rate_limited: retry_after invalid_api_key: no_retry schema_parse_failed: maybe_retry限流错误最好带 retry_after避免调用方疯狂重试。四、不要吞掉底层原因SDK 可以包装错误但不要把底层状态码、请求 ID、供应商错误码全部丢掉。排查线上问题时这些信息很重要。throw new AiSdkError(PROVIDER_TIMEOUT, { provider, requestId, cause: err, });同时要注意脱敏。错误对象不要包含 API Key 或完整用户输入。最后错误码要写进文档。开发者知道哪些错误会出现才能写出可靠集成。错误对象还要支持序列化。很多 SDK 会在前端、后端、Worker、队列之间传递错误如果错误不能稳定转成 JSON调用方只能拿到一段 message。class AiSdkError extends Error { toJSON() { return { code: this.code, message: this.message, retryable: this.retryable }; } }还要保持错误码向后兼容。开源 SDK 一旦发布调用方可能已经在代码里判断RATE_LIMITED。随意改名会破坏用户逻辑。新增错误码可以删除或改语义要走 major 版本。文档里最好给恢复示例。比如遇到限流如何退避遇到 schema 失败如何重试遇到配置错误如何提示用户。错误码只有和处理代码一起出现开发者才真正能用。最后测试要覆盖错误路径。只测成功调用的 SDK离可用还差很远。错误码还要区分用户可见和开发者可见。用户界面需要简洁提示开发者日志需要 request id、供应商、状态码和排查建议。SDK 可以提供两个层级的格式化方法。error.toUserMessage(); error.toDebugJSON();还要支持国际化但 code 必须保持不变。message 可以翻译code 不能翻译否则程序判断会失效。最后错误码设计要有注册表。新增 code 时检查是否重复、是否已有相似语义避免错误体系慢慢膨胀成一堆别名。五、总结AI SDK 错误码设计要分类、稳定、可重试语义清晰并保留必要底层上下文。给开发者一个能处理的失败比给一段漂亮报错更重要。