3 步开发者的 API 故障医生
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_8ee65e73/api-error-doctor。
技能介绍
要解决什么问题
调用第三方或自建 API 时,最常卡住的往往不是「会不会写请求」,而是 错误响应看不懂:HTTP 状态码、error_code 与文档对不上、响应体里嵌套多层 JSON,或日志里只有一句 Connection reset。单靠搜索引擎往往只能碰到零碎帖子,很难把当前这一次失败收敛成可执行的修复路径。
「3 步开发者的 API 故障医生」面向这类 接口联调与线上排障 场景,把排错过程收成可重复的结构,而不是泛泛的「检查一下网络」。
技能如何工作
技能名里的「三步」对应一条从现象到结论的链路,典型会引导你:
- 锁定上下文:方法、URL、状态码、请求头/体摘要、以及完整或截断的错误响应
- 对照语义:把状态码、常见厂商错误字段与文档条目对齐,区分鉴权、限流、参数校验、服务端异常等类别
- 给出可验证的下一步:改什么参数、换哪个凭证、补哪段日志,并说明如何复现以确认修复
在与模型对话时,你提供报错片段或 curl/客户端日志即可;技能会按步骤追问缺失信息,避免在信息不全时瞎猜根因。对 4xx/5xx、OAuth token、GraphQL errors 数组、以及带 request_id 的云 API 响应,都适合做 逐项拆解 而非只复述错误文案。
适用边界与注意点
本技能擅长 解读已有错误信号并缩小原因范围,不能替代你在本机/内网直接抓包或读服务端源码。若错误来自本地网络策略、证书链或 DNS,仍需结合 openssl、dig 或运维配置排查。
敏感信息(生产密钥、完整 Cookie、用户 PII)应在粘贴前打码;技能依赖你提供的响应是否与真实环境一致,伪造或过时的示例 会导致结论偏差。未在 SKILL 中声明的专有平台内部错误码,结论应视为假设,需以官方状态码表或支持工单为准。
使用场景
- 对接支付或短信网关时收到 401/403,需要对照文档判断是签名算法还是密钥环境用错
- 生产环境间歇性 502,只有上游返回的 JSON 错误体,需要梳理是超时、限流还是路由问题
- Webhook 回调验签失败,要把请求头、原始 body 与平台文档里的校验步骤逐条对齐
- 调用云厂商 OpenAPI 返回带 RequestId 的业务错误,需要把 error code 映射到可改的参数或配额项
适合人员
- 正在接入第三方支付接口、需要把拒单错误码翻译成配置项的后端工程师
- 负责维护 BFF 或网关层、经常要把下游 4xx/5xx 日志整理成给产品或客服说明的全栈开发
- 每周处理多条客户「接口调不通」工单、需要快速判断是参数问题还是对方服务异常的技术支持
- 在 CI 里跑集成测试、失败时只有截断响应体、需要结构化追问遗漏字段的测试开发