接口文档里最容易漏掉的，是失败分支怎么收尾

一份接口文档如果只告诉调用方成功时能拿到什么，通常还不够。真正让人踩坑的，往往是超时、重复提交、幂等冲突和部分成功这些边角处。

我会补上的四类信息

• 哪些错误码需要重试，哪些不该重试
• 幂等键怎么生成，多久失效
• 调用超时后，服务端是否可能还在继续处理
• 回调失败或部分成功时，调用方应该怎样补偿

真正让协作顺起来的，不是把 happy path 讲得很漂亮，而是把收尾动作说明白。