错误码与排查
业务结果以 JSON 的 code 为准：code === 1 成功，否则失败；error 是机器可读错误码，data 是中文说明。
| 错误码 | 原因 | 处理 |
|---|---|---|
| DEVELOPER_LOGIN_REQUIRED | 开发者控制台登录过期 | 重新登录开发者中心 |
| DEVELOPER_ACCOUNT_EXISTS | 手机号或邮箱已注册开发者账号 | 直接登录，或换用其他账号注册 |
| VERIFY_CODE_TOO_FREQUENT / VERIFY_CODE_RATE_LIMITED | 验证码发送过于频繁 | 等待倒计时结束后重试 |
| VERIFY_CODE_DAILY_LIMIT | 账号或当前网络今日发送次数达到上限 | 次日再试或联系平台处理 |
| INVALID_VERIFY_CODE / VERIFY_CODE_EXPIRED / VERIFY_CODE_ATTEMPTS_EXCEEDED | 注册验证码错误、过期或错误次数过多 | 重新获取验证码并在 5 分钟内完成注册 |
| VERIFY_SERVICE_NOT_CONFIGURED / VERIFY_CODE_SEND_FAILED | 短信或邮件服务未配置、发送失败 | 检查开放平台验证码服务环境变量和服务商状态 |
| APP_AUTH_REQUIRED | 创建会话没带 appSecret | 后端增加 Bearer Authorization |
| APP_AUTH_FAILED | 密钥错误、已重置或应用已删除 | 更新后端 appSecret |
| ALLOWED_ORIGIN_REQUIRED | 应用没有填写允许嵌入域名 | 在应用管理中至少填写一个完整 Origin |
| PARENT_ORIGIN_REQUIRED | 没有传有效 parentOrigin | 传完整 Origin，例如 https://hr.example.com |
| ORIGIN_NOT_ALLOWED | parentOrigin 不在应用白名单 | 在应用管理中添加完全一致的协议、域名和端口 |
| EXTERNAL_RESUME_ID_REQUIRED | externalResumeId 缺失或超过 128 个字符 | 传当前应用内唯一且稳定的简历 ID |
| INVALID_CODE | editorUrl 超过 60 秒或使用过一次 | 重新创建会话，立即打开新 URL |
| EDITOR_AUTH_REQUIRED | editorToken 过期 | 关闭编辑器并重新创建会话 |
| SESSION_EXPIRED | 临时会话超过 24 小时 | 使用相同 externalResumeId 和接入方保存的 JSON 重新创建会话 |
| VERSION_CONFLICT | 同一会话多页同时保存 | 关闭重复页签后重开 |
| SESSION_BALANCE_INSUFFICIENT | 当前会话可消费额度不足 | 完成接入方自己的收费或授权流程后，用 appSecret 增加会话额度 |
| DEVELOPER_BALANCE_INSUFFICIENT | 开发者人民币账户余额不足 | 开发者充值账户余额；不要让最终用户购买个人 VIP |
| ID_PHOTO_RECHARGE_REQUIRED | 开发者账户从未充值，当前只有注册赠送余额 | 开发者账户完成一次充值后即可制作证件照 |
| PDF_EXPORT_RECHARGE_REQUIRED | 开发者账户从未充值，当前只有注册赠送余额 | 开发者账户完成一次充值后即可导出或生成简历 PDF |
| INVALID_REQUEST_ID | requestId 缺失或格式错误 | 传 8～64 位字母、数字、下划线、冒号或连字符 |
| REQUEST_ALREADY_PROCESSED | requestId 已经用于其他收费请求 | 不要在请求仍在等待时重试；新业务请求使用新的 ID |
| RESUME_SOURCE_REQUIRED | 解析 API 未收到文件或简历内容 | 使用 multipart 上传 file，或用 JSON 提交 content |
| MULTIPLE_RESUME_SOURCES | 同时提交了文件和 content | 两种输入只保留一种 |
| RESUME_FILE_TOO_LARGE | 文件为空或超过 3MB | 压缩文件后重新上传 |
| UNSUPPORTED_RESUME_FILE / INVALID_RESUME_FILE | 格式不支持、扩展名不匹配或文件损坏 | 重新导出 PDF、DOC、DOCX 或 TXT 后上传 |
| RESUME_CONTENT_TOO_SHORT | 内容太短或文件无法提取文字 | 补充简历内容；扫描 PDF 请先转成可选中文字的文件 |
| RESUME_PARSE_FAILED | AI 未返回合法结构化数据 | 本次费用会自动退回，可使用新的 requestId 重试 |
| INVALID_TEMPLATE_ID / TEMPLATE_NOT_FOUND | PDF API 的 resumeData.setData.tplId 格式错误或不存在 | 从模板列表接口选择 ID 写入 tplId，或不传以使用默认模板 1013 |
| INVALID_RESUME_DATA / RESUME_DATA_TOO_LARGE | PDF API 的 resumeData 不是对象或超过 2MB | 按简历 JSON 文档整理并压缩数据 |
| UNSAFE_RESUME_DATA | resumeData 含脚本、iframe 等不安全内容 | 删除可执行标签和 javascript: 地址 |
| FEATURE_DISABLED | 创建会话时关闭了该能力 | 重新创建会话并开启对应 features 开关 |
父页面收不到 saved
- 确认父页面实际 Origin 与创建会话的
parentOrigin完全一致。 - 确认该 Origin 已配置到应用“允许嵌入域名”。
- 确认监听器校验的是
https://www.qmjianli.com，不是 API 地址。 - 确认监听器在 iframe 加载前已注册。
- 确认监听的是
event === "saved"。
iframe 打不开
- 缺少授权码：没有使用接口原样返回的 editorUrl。
- 授权码无效：创建后超过 60 秒才设置 src，或在另一个 iframe 中重复使用旧 URL。
- 编辑会话失效：会话已超过 24 小时；使用相同 externalResumeId 重新调用创建接口即可。
PDF 下载失败
- 生成接口会同步等待数秒，不要按异步 jobId 方式轮询。
- 临时地址过期后不支持恢复，让用户重新导出。
- 会话额度不足时通过
session_balance_insufficient通知；开发者余额不足时通过developer_balance_insufficient通知。 - PDF 导出失败时，本次 2 元费用会自动退回会话额度和开发者账户余额。