错误码参考
HTTP 层
| 状态 | 说明 |
|---|
| 200 | 成功 |
| 202 | 已接受（token 发送、密码重置请求等异步操作） |
| 400 | 请求参数错误 |
| 401 | 认证失败（Key 无效/过期/格式错误） |
| 402 | 积分不足（insufficient_credits） |
| 403 | 权限不足（资源不属于当前 principal） |
| 404 | 资源不存在 |
| 409 | 状态冲突（如重复创建、已核销） |
| 429 | 限流（见下方 rate-limit 错误码） |
| 500 | 服务器内部错误（请带上 x-request-id 联系我们） |
Rate Limit 错误码（429）
| 错误码 | 说明 |
|---|
api_key_rate_limited | 触发每分钟请求数上限，等待窗口滚动 |
api_key_concurrent_job_limit_exceeded | 当前并发作业数达上限，等已排队作业完成 |
api_key_daily_job_limit_exceeded | 触发当日作业数上限，等次日零点（UTC）重置 |
作业失败码（failed 状态下的 failure_code）
平台侧失败（自动退回积分）：
| 错误码 | 触发条件 |
|---|
turnitin_blocked | Turnitin 拒绝本次请求（限流 / 风控 / 验证码） |
login_failed | 账号池登录失败（密码错误/账号禁用） |
upload_failed | 文档上传至 Turnitin 失败 |
report_timeout | 报告生成超过最大等待时间（默认 10 分钟） |
system_error | 内部异常（会抓堆栈，请反馈） |
用户侧失败（积分扣除不回滚）：
| 错误码 | 触发条件 |
|---|
document_unreadable | 文档损坏或加密导致无法提取文本 |
document_too_short | 字数过少（< 20 词） |
unsupported_language | 上游不支持的语言 |
如何判断需要重试
- 429 / 5xx：可重试，建议指数退避 1s → 2s → 4s → 8s
- 平台侧失败码：自动退款了，你可以用退回的积分立即重试一次
- 用户侧失败码：先修复文档再重试，否则还是失败
- 402 / 401 / 403 / 404 / 409：不要盲目重试，请先处理参数/状态
报告问题
每个响应都带 x-request-id。收到非预期的错误时请连同 request-id 发送到 support@njbejm.cn。