错误码

当请求失败时，API 返回包含机器可读 code 和人类可读 message 的 JSON 错误响应：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

code 字段是稳定的，可以安全地在应用逻辑中进行匹配。message 字段可能随时间变化，主要用于日志记录和调试。

错误码参考

错误码	HTTP 状态码	描述	可重试	解决方法
UNAUTHORIZED	401	缺少、无效或已过期的认证令牌	否	检查您的 API 密钥是否有效且未过期
KEY_EXPIRED	401	API 密钥已超过过期日期	否	在控制面板或通过 API 创建新的 API 密钥
FORBIDDEN	403	已认证但无权访问此资源	否	您只能访问自己的资源
NOT_FOUND	404	请求的资源不存在	否	验证资源 ID 是否正确
VALIDATION_ERROR	400	请求体未通过模式验证	否	检查必填字段和数据类型是否匹配模式
INVALID_MIME_TYPE	400	上传的文件 MIME 类型不受支持	否	使用受支持的文件类型（PDF 或 DOCX）
FILE_TOO_LARGE	400	上传的文件超过 10 MB 大小限制	否	减小文件大小或拆分为较小的文档
MAX_KEYS_REACHED	400	已达到 10 个有效 API 密钥的上限	否	在创建新密钥之前吊销未使用的密钥
USAGE_LIMIT_EXCEEDED	429	月度提取限额已用完	否	升级计划或等待下一个计费周期
INTERNAL_ERROR	500	意外的服务器错误	是	使用指数退避重试。如果持续出现，请联系支持
NOT_CONFIGURED	501	所需的服务端服务未配置	否	联系支持 -- 这表示服务器配置问题
EXTRACTION_FAILED	502	AI 提取处理失败	是	重试 -- 可能是暂时性问题。检查 PDF 是否有效且可读
EXTRACTION_PARSE_ERROR	502	AI 返回的响应无法解析为 JSON	是	重试 -- AI 可能在后续尝试中产生有效输出

可重试的错误

仅以下错误码应该重试：

• INTERNAL_ERROR -- 服务端发生意外故障。
• EXTRACTION_FAILED -- AI 提取过程失败，通常是暂时性问题。
• EXTRACTION_PARSE_ERROR -- AI 返回了无法解析的格式错误输出。

重试时，使用从 1 秒开始的指数退避，最多重试 3 次：

尝试次数	延迟
第 1 次重试	1 秒
第 2 次重试	2 秒
第 3 次重试	4 秒

如果 3 次重试后请求仍然失败，请记录错误并将其反馈给用户或您的监控系统。

关于实现重试逻辑的完整指南，请参见错误处理。

HTTP 状态码摘要

状态码	含义
200	成功 -- 请求已成功完成
400	错误请求 -- 验证错误、无效文件类型、文件过大或密钥数量已达上限
401	未授权 -- 认证失败（令牌缺失、无效或已过期）
403	禁止访问 -- 已认证但无权访问请求的资源
404	未找到 -- 请求的资源不存在
429	请求过多 -- 月度提取用量限额已超出
500	内部服务器错误 -- 服务端发生意外故障
501	未实现 -- 所需的服务端服务未配置
502	网关错误 -- AI 提取或解析失败