API 密钥与调用安全

准备 API Key

在控制台右上角头像菜单进入 Settings，然后打开个人中心的 API Key 页面生成密钥。每个账号仅一个有效 Key；重新生成后旧 Key 立即失效，完整 Key 仅生成时展示一次。所有请求使用 X-API-Key；POST 另加 Content-Type: application/json。不需要网页登录 JWT、Cookie、Device-ID、hash 或 platform；Bearer Token 不能代替此请求头。

API Key 安全管理

将密钥保存在服务端的环境变量或密钥管理系统，不嵌入前端、公开仓库或客户端。不要写入 URL、请求体、日志或工单；示例用环境变量 API_KEY。在可信环境生成和保存，泄露时立即轮换或禁用，并更新所有调用方。轮换后旧 Key 无效，禁用后请求被拒绝。

错误处理与重试

400 修正参数；401/403 检查密钥或账号；409 修复资源或等待冲突结束；429 退避重试。查询可在额度内重试。写操作无对外幂等键约定：超时或 500 后是否受理可能不确定，先核实再决定是否重试。安装应用不存在、版本不匹配或云端提交失败目前也可能返回 500 / PUBLIC_API_INTERNAL_ERROR，不能当作未执行的证明。

接入验证与支持

提交问题时提供 request_id、接口路径、HTTP 状态、reason、发生时间及脱敏参数；不要提交 API Key。先用只读列表验证接入，再在明确授权的测试设备上执行写操作，确认结果后再扩大批次。

相关文档

• 公共 API 使用指南
• 服务问题排查与工单信息