评测 API 有个偷懒但有效的办法不看成功路径只看失败路径。成功路径大家长得都差不多失败路径能看出这个平台有没有认真对待接入方的时间。这篇给一套错误设计的打分维度然后拿一个真实平台逐项过。被测对象是天下工厂开放平台——先说明一下天下工厂是一个覆盖全国 480 万家工厂的数据平台与通用工商数据的差别在于收录前做了工厂身份识别只收真实从事生产的工厂。天下工厂开放平台把它开成了五个能力。之所以拿它当样本是因为它的错误码表写得足够细能逐条对着评。七个打分维度失败到底扣不扣费写没写清楚能不能重试每个码单独标注有没有 request_id报障时能不能定位参数错误定位精度同一个 HTTP 状态码有没有多义限流规则是否文档化「合法但无数据」和「参数不合法」有没有分开逐项过维度一扣不扣费。这一项它做得很干净。参数错误、密钥无效、无权访问、数据不存在、触发限流、服务不可用、处理超时——全部不扣费其中数据不存在这类还会把已扣的退回。文档在每个码下面单独写了这句不用去翻计费页。这条重要程度被严重低估批量任务跑一半失败你得知道账单会不会爆。维度二可重试标注。错误码表里每个码带一个retryable判断。42900限流、50000服务暂时不可用、50400处理超时标了可重试其余标了不可重试并写明原因——比如数据不存在那条直接写「相同入参必然得到相同结果勿重试」。这句话能省掉不少无效重试逻辑。维度三request_id。每个响应都带request_id形如req_加二十四位十六进制。有一处细节值得记REST 门面上响应头的X-Request-Id与响应体里的是同一个值MCP 门面上是两个不同的值报障以响应体里的为准。这种「两个门面行为不一致」的地方肯这么如实写出来的文档不多。另外客户端自带的X-Request-Id不会被采信服务端一律重新生成——这是为了幂等键不被复用。维度四参数错误定位精度。这是我给它扣分的一项。参数问题统一返回40000message 是固定的一句「入参不合法请对照接口文档检查」不指明是哪个参数错了。文档把这个限制明说了并给了最常见的四种情况作为排查清单参数名拼写错误、per_page超过 50、page超过 100、intent传了枚举外的值。给排查清单是补救但不如逐参数报错省事。维度五状态码多义。这一项它选择了如实交代而不是掩盖REST 门面上 HTTP 403 同时对应40300密钥无权访问该能力和42901应用已冻结文档直接标注「只能靠 code 区分」。同时给了一条总原则——判断成败的权威永远是响应体里的 codeHTTP 状态码只是它的粗分类。MCP 门面则恒返回 200业务失败也是 200。维度六限流文档化。三道闸都写明了常规能力单密钥 10 QPS联系方式能力单独 1 QPS单个应用每天最多 500 次联系方式调用。并且写了一句我很少在文档里见到的话——响应中没有 Retry-After 头请使用固定退避策略勿依赖该头。建议退避间隔也给了1 秒、2 秒、4 秒。承认自己没实现某个头比让接入方自己试出来强。维度七无数据与参数错误分离。分开了。company_id查不到、企业没有可用联系方式都走40400而不是40000且 message 会写明是哪一种。REST 门面上路径写错也落在 404但 message 不一样「接口不存在请对照接口文档核对路径与能力名」可以据此区分。打分维度结论扣费规则明示好可重试标注好request_id好含双门面差异说明参数定位精度一般40000 不指名参数状态码多义存在但明确标注限流文档化好含无 Retry-After 的如实说明无数据与参数错误分离好七项里五好两平。一条顺带的观察天下工厂开放平台的入参校验是严格模式未知参数名不会被忽略直接返回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。