下午五点半，客户发来截图：「系统又报签名错误了，你们代码是不是有问题？」这种对话在API接口对接的联调期，几乎每周都会上演。先别急着互相甩锅，绝大多数对接故障都落在三类坑里，按顺序排查，十有八九当天能解决。
第一坑：签名错误
签名错误九成不是算法写错，而是细节没对齐：密钥复制时带了空格或换行、时间戳用了秒对方要毫秒、参数排序规则不一样、中文没做URL编码。排查办法很笨但有效——把参数按文档规则手工拼一遍签名，和代码生成的对比，哪个参数对不上，问题就藏在哪。开放平台文档里的签名校验工具用起来，比肉眼盯着参数表快得多。
第二坑：请求超时
本地跑得好好的，一部署到服务器就超时，八成是出口IP不在对方的白名单里，或者服务器走了代理被拦。先在服务器上用curl直接打对方接口，绕开你自己的业务代码，两分钟就能分清是网络问题还是代码问题。接口超时时间记得设短一点配重试，别让一个第三方故障把你自己的页面也拖死，这种连带事故比接口本身失败更伤。
第三坑：回调收不到
下单成功，回调地址就是没收到通知。先自查三件事：回调地址外网能不能访问，防火墙和安全组放行了没；是不是HTTPS证书过期了；对方要求的应答格式你返回对了没。有些平台的回调只推五次，全错过就得用查询接口主动补。所以业务上永远要留一条主动查询的兜底路，不能干等通知。
举个联调期的真实场景：一家客户的系统连着三天凌晨两点准时报签名错误，白天一切正常。最后查出来是对接平台的密钥每天凌晨定时轮换，而客户这边把密钥写死在了配置文件里。把密钥改成定时拉取，问题消失。你看，这种问题不看日志永远想不到，排查的功夫全在平时留没留痕迹上。
最后给两条建议：联调期把每次请求和响应完整记进日志，出了纠纷有据可查；找外包做对接时，把API接口对接的日志方案和排查文档写进交付清单。比格网络交付对接类项目时都会带一份常见报错对照表，客户自己就能先排查一轮，这种小文档能省下大量来回扯皮的时间。
