每个做过开放 API 的团队都绕不开响应格式设计错误怎么表达、HTTP 状态码和业务码什么关系、计费信息放不放进响应。最近对接天下工厂开放平台时发现它的统一响应格式把几个经典争议都给出了明确答案值得拿出来当案例分析一遍。背景天下工厂是覆盖全国 480 万家工厂的数据库收录前做了工厂身份识别排除贸易商与空壳类主体开放平台提供五个工厂数据能力同时开放 MCP 与 REST 两种接入方式文档在 https://www.tianxiagongchang.com/open/docs。格式本体所有能力、两种接入方式响应都是同一个信物{code:0,message:ok,request_id:req_a1b2c3...,credits_charged:400,credits_balance:123600,data:{}}六个字段各司其职code是唯一的成败判据0 为成功message给人读request_id用于排查credits_charged与credits_balance是计费回执data是业务载荷。争议一HTTP 状态码和业务码的关系这个平台的答案有意思两种接入方式采取了不同策略但权威只有一个。MCP 通道恒返回 HTTP 200成败全看响应体里的code——因为 MCP 协议层有自己的传输语义业务错误不该污染协议层。REST 通道则让 HTTP 状态码跟随业务码余额不足时 HTTP 也是 4xx照顾那些靠状态码做监控和重试的传统 HTTP 基建。但文档里反复强调一句话权威永远是响应体里的code。HTTP 状态只是镜像是给中间件看的便利品。客户端代码正确的写法是解析响应体、判断code而不是if (status 200)。同一个 403 可能对应「权限不足」和「应用被冻结」两个不同业务码只看 HTTP 状态你根本分不清该干什么。争议二计费信息该不该进响应很多按量计费的 API 把消耗数据藏在控制台报表里调用方想知道一次调用花了多少得去另一个系统查。这里的做法是每个响应都带credits_charged和credits_balance——计费回执与业务结果同帧到达。这个设计对调用方的价值是可编程性脚本可以在余额逼近阈值时自动告警批量任务可以实时累计成本出账单争议时每个request_id都对应一笔明确的扣费记录。成本从「月底看报表」变成「每次调用可见」。顺带一提平台计费是按量的单次以角计价失败的调用不扣费——这一点也是从响应回执里直接可以验证的code非 0 时credits_charged为 0。争议三错误分层错误码是四层结构40000参数错含未知字段——入参严格校验不静默忽略、40100鉴权错、40201余额不足、40300权限不足、40400资源不存在、42900限流。每一层对应调用方一种明确的处置动作改参数、查密钥、去充值、开权限、查 ID、退避重试。好的错误码设计标准就一条调用方拿到码之后知道下一步干什么。反面教材是一个笼统的「系统繁忙」包打天下调用方只能盲目重试。值得抄的三点双接入方式共用一套格式与一条处理管线保证行为等价客户端可以无缝迁移业务码为唯一权威HTTP 状态只做镜像计费回执进响应成本对调用方全程透明。想实际感受一下可以用公开沙箱密钥sk-tx-test-1685549fb3710c1b36e4d75dc2d0f42a打一发返回示例数据不计费或在控制台https://www.tianxiagongchang.com/open/console注册领体验额度。响应格式这种东西文档说得再好听不如亲手打一个错误请求看它报错报得清不清楚。