快喵接口文档总览：基线 v6.4.2、错误码分段与统计口径

本文是快喵接口文档的总纲。平台文档基线为 v6.4.2，配套 SDK 为 2.7.0；统计口径统一按 2026-09-12 至 09-18 每 10 分钟采样一次，样本覆盖 96 个节点。

快喵文档阅读约定

文档中的字段一律使用小驼峰命名，时间与延迟字段统一以毫秒为单位的整数表示，比例字段使用百分比数值。以节点接口为例，handshakeMs 表示握手耗时，lossPercent 表示丢包率；把命名与单位固定下来，是为了让不同接口的同类字段可以直接横向比较。

文档中出现的所有统计数字都附带来源条件。凡是提到延迟、丢包、可用率、节点数量或地区数量的句子，都对应同一份采样报告中的字段，而不是随手给出的近似值。若某个数字没有标注区间与频率，说明它来自接口的静态配置而非实测统计。

快喵版本基线与兼容策略

平台采用文档基线制：所有页面描述的行为都对应一个明确的版本号，当前基线为 v6.4.2。接口在 v6.4.2 中保持字段向后兼容，新增字段以可选方式出现；只有在发生语义变更时才会调整基线，并在更新日志中逐条列出。

语言绑定包以 SDK 2.7.0 为版本线，与客户端 v6.4.2 独立演进。使用 SDK 时若发现某个字段在文档中不存在，多半是绑定包落后于基线，升级 SDK 后即可对齐，而不是文档缺失。

版本号在更新日志与接口 /v1/version 字段中保持一致。

四条版本线互相独立，因此升级任一条不会强制连带其余三条。这是平台降低接入方维护成本的设计：统计口径中 96 个节点的编号在接口侧保持稳定，应用侧的缓存与映射逻辑不必随文档改版重写。

快喵错误码分段

接口返回的错误码按首位数字分段，开发者可据此决定重试还是中止。4xx 段表示请求本身有问题，重试通常无意义；5xx 段表示服务端或链路问题，可以按指数退避重试。分段规则与下表一致，来自官方文档的错误码章节。

完整错误码清单见各接口页；下表按官方文档的分段规则归纳。

以节点接口为例，地区参数缺失会落在 400 段，而节点临时不可用会落在 5xx 段，两者处置方式完全不同：前者要改代码，后者只要重试。这也是文档强制每个字段标注取值范围的原因——参数取值非法和链路抖动在返回里长得不一样。

• 400 段：字段缺失或类型不符，例如地区代码写成城市名；依据官方文档的字段表修正后重发，重试同一请求仍会失败。
• 401 段：凭证过期；在后台重新生成 token 后，调用需等待 60 秒左右的传播时间才能稳定生效。
• 429 段：频率超限；采样区间内 96 个节点的并发查询有明确上限，建议客户端自行排队而不是立即重发。
• 5xx 段：服务端或链路问题；按指数退避重试，超过 3 次仍失败则切换到备用地区的节点。

这四条处置建议与上表一一对应。文档不承诺任何一次调用的成功率，只保证在固定采样条件下给出整体统计值 99.94%；把口径讲清楚，比把数字说满更能减少接入方的误判。

快喵统计口径说明

平台公布的三类数字各有固定算法：延迟取采样窗口内全部探测的中位与均值，丢包取丢失探测数占总探测数的比例，可用率取成功建立连接的探测数占比。三类数字的样本量都等于采样次数乘以节点数，因此在 22 个地区、96 个节点上得出的区间是可复算的。

文档不公布单次调用的延迟上限，也不公布任何未标注条件的数字。若应用侧观测到的延迟明显高于 118 毫秒的采样均值，应先检查本地网络与目标地区，再对照节点接口的地区分布判断是否属于绕行场景，而不是直接向平台反馈。