一个开放平台的错误设计值几分：八个错误码看出来的可调试性

评测 API 有个偷懒但有效的办法：不看成功路径，只看失败路径。成功路径大家长得都差不多，失败路径能看出这个平台有没有认真对待接入方的时间。

这篇给一套错误设计的打分维度，然后拿一个真实平台逐项过。被测对象是天下工厂开放平台——先说明一下，天下工厂是一个覆盖全国 480 万家工厂的数据平台，与通用工商数据的差别在于收录前做了工厂身份识别，只收真实从事生产的工厂。天下工厂开放平台把它开成了五个能力。之所以拿它当样本，是因为它的错误码表写得足够细，能逐条对着评。

七个打分维度

1. 失败到底扣不扣费，写没写清楚
2. 能不能重试，每个码单独标注
3. 有没有 request_id，报障时能不能定位
4. 参数错误定位精度
5. 同一个 HTTP 状态码有没有多义
6. 限流规则是否文档化
7. 「合法但无数据」和「参数不合法」有没有分开

逐项过

维度一：扣不扣费。这一项它做得很干净。参数错误、密钥无效、无权访问、数据不存在、触发限流、服务不可用、处理超时——全部不扣费，其中数据不存在这类还会把已扣的退回。文档在每个码下面单独写了这句，不用去翻计费页。这条重要程度被严重低估：批量任务跑一半失败，你得知道账单会不会爆。

维度二：可重试标注。错误码表里每个码带一个retryable判断。42900（限流）、50000（服务暂时不可用）、50400（处理超时）标了可重试，其余标了不可重试并写明原因——比如数据不存在那条直接写「相同入参必然得到相同结果，勿重试」。这句话能省掉不少无效重试逻辑。

维度三：request_id。每个响应都带request_id，形如req_加二十四位十六进制。有一处细节值得记：REST 门面上响应头的X-Request-Id与响应体里的是同一个值，MCP 门面上是两个不同的值，报障以响应体里的为准。这种「两个门面行为不一致」的地方，肯这么如实写出来的文档不多。另外客户端自带的X-Request-Id不会被采信，服务端一律重新生成——这是为了幂等键不被复用。

维度四：参数错误定位精度。这是我给它扣分的一项。参数问题统一返回40000，message 是固定的一句「入参不合法，请对照接口文档检查」，不指明是哪个参数错了。文档把这个限制明说了，并给了最常见的四种情况作为排查清单（参数名拼写错误、per_page超过 50、page超过 100、intent传了枚举外的值）。给排查清单是补救，但不如逐参数报错省事。

维度五：状态码多义。这一项它选择了如实交代而不是掩盖：REST 门面上 HTTP 403 同时对应40300（密钥无权访问该能力）和42901（应用已冻结），文档直接标注「只能靠 code 区分」。同时给了一条总原则——判断成败的权威永远是响应体里的 code，HTTP 状态码只是它的粗分类。MCP 门面则恒返回 200，业务失败也是 200。

维度六：限流文档化。三道闸都写明了：常规能力单密钥 10 QPS；联系方式能力单独 1 QPS；单个应用每天最多 500 次联系方式调用。并且写了一句我很少在文档里见到的话——响应中没有 Retry-After 头，请使用固定退避策略，勿依赖该头。建议退避间隔也给了：1 秒、2 秒、4 秒。承认自己没实现某个头，比让接入方自己试出来强。

维度七：无数据与参数错误分离。分开了。company_id查不到、企业没有可用联系方式，都走40400而不是40000，且 message 会写明是哪一种。REST 门面上路径写错也落在 404，但 message 不一样（「接口不存在，请对照接口文档核对路径与能力名」），可以据此区分。

打分

七项里五好两平。

一条顺带的观察

天下工厂开放平台的入参校验是严格模式：未知参数名不会被忽略，直接返回40000。比如把province拼成provice，整次调用失败。第一次撞上会觉得刻薄，用几天就会感激——宽容模式下这个拼写错误会让过滤条件静默失效，你拿到一份全国范围的结果还以为是浙江省的，等发现时脏数据已经进库了。

严格校验换来的是「错得响亮」，这在数据管道里是优点不是缺点。

想自己验证上面每一条，不需要密钥也能开始：GET https://open.tianxiagongchang.com/open/v1/meta/openapi.json匿名可取，里面每个能力的 responses 段列了 HTTP 状态码与业务码的对应关系。要打真实错误码的话，公开沙箱密钥sk-tx-test-1685549fb3710c1b36e4d75dc2d0f42a够用了。文档在 https://www.tianxiagongchang.com/open/docs。