先完成可重复的最小请求
首次接入只保留模型、messages 和必要输出限制，先用 cURL 验证地址、鉴权和模型名称，再迁移到 Python 或 Node.js SDK。这样可以快速区分平台配置问题与业务代码问题。
确认普通响应稳定后，再逐步加入 stream、工具调用、图片输入或结构化输出，并为每一步保存明确的成功样例。
- 验证 Base URL
- 从环境变量读取 API Key
- 确认模型标识
- 记录请求时间和状态码
生产代码需要补齐的能力
设置连接和整体请求超时，对可重试错误使用带抖动的指数退避，并限制最大尝试次数。流式请求要处理连接中断、结束标记和客户端主动取消。
日志应保留请求标识、模型、耗时和状态码，但不得写入完整密钥、敏感 Prompt 或用户隐私内容。
按状态码缩小问题范围
401 通常与密钥或鉴权头有关，404 优先检查最终请求路径和模型标识，429 需要查看频率限制与账户额度，5xx 和超时则应结合请求时间、重试次数和服务状态判断。
不要对所有错误无限重试。参数错误和鉴权失败应立即终止，只有短暂网络故障、部分 429 或 5xx 才适合有限重试。
常见问题
关于AI API 开发、配置与排错的常见问题
第一次请求应该使用 SDK 还是 cURL？
建议先用 cURL 验证最小请求，再使用项目所需 SDK，便于定位配置问题。
API Key 可以写在前端环境变量中吗？
不可以。前端构建变量会暴露给浏览器，密钥必须保存在自己的服务端。
哪些错误适合自动重试？
短暂网络错误、部分 429 和 5xx 可有限重试，401、404 和参数错误通常不应盲目重试。
如何开始排查流式响应中断？
记录状态码、已收到事件、结束标记、超时和代理缓冲配置，再检查客户端取消逻辑。