API 错误码 · 文档预览接入排查

本页内容

错误响应

统一格式

json

{"ok":false,"error":"错误说明","error_code":"API_KEY_MISSING","message":"错误说明"}

HTTP 状态用于大类判断，业务逻辑请以 error_code 为准；文案可能优化，不应作为程序分支条件。

HTTP	错误码	含义	调用方动作
401	`API_KEY_MISSING`	缺少 API Key	补充 X-Api-Key 请求头
401/403	`API_KEY_INVALID`	API Key 无效	检查凭证是否完整及是否已轮换
403	`API_KEY_DISABLED`	Key 已禁用	在客户中心检查 Key 状态
403	`API_KEY_EXPIRED`	Key 已过期	联系管理员调整有效期
403	`API_ORIGIN_FORBIDDEN`	请求来源不被允许	检查来源白名单及无来源请求设置
401	`API_SIGNATURE_INVALID`	签名或时间戳无效	检查原始 Body、密钥及 300 秒时间窗口
401	`API_SIGNATURE_REPLAYED`	同一签名重复使用	保留业务幂等键，使用新的秒级时间戳重新签名

HTTP	错误码	含义	调用方动作
400	`INVALID_REQUEST`	请求格式无效	检查 JSON 或表单格式
422	`IDEMPOTENCY_KEY_REQUIRED`	缺少幂等键	使用业务文件唯一标识
422	`PREVIEW_PARAMS_INVALID`	预览参数不合法	按参数表修正类型或范围
422	`SOURCE_INVALID`	来源 URL 格式无效	使用 HTTP/HTTPS URL
403	`SOURCE_REJECTED`	来源地址被安全策略拒绝	确认公网 DNS 和下载地址

HTTP	错误码	含义	调用方动作
429	`API_RATE_LIMITED`	请求频率超限	退避后重试，避免持续并发重放
503	`API_RATE_LIMIT_UNAVAILABLE`	频率校验暂不可用	稍后重试并保留请求 ID
503	`API_SIGNATURE_REPLAY_UNAVAILABLE`	签名校验存储暂不可用	稍后重试并使用新的签名
429	`API_QUOTA_EXHAUSTED`	免费或购买额度已用完	联系客服增加额度
429	`API_DAILY_LIMITED`	达到每日调用上限	降低调用频率或调整限额

HTTP	错误码	含义	调用方动作
400	`UPLOAD_INVALID`	multipart 格式无效或请求体超过解析上限	检查上传格式及请求总大小，不要反复提交超大文件
400	`UPLOAD_FILE_REQUIRED`	缺少 file 字段	以 multipart/form-data 上传文件
413	`UPLOAD_TOO_LARGE`	文件超过大小限制	压缩文件或联系管理员
415	`UPLOAD_TYPE_UNSUPPORTED`	文件类型不支持	检查支持格式和扩展名

HTTP	错误码	含义	调用方动作
404	`TOKEN_INVALID`	Token 不存在或格式无效	检查完整预览地址
410	`TOKEN_EXPIRED`	Token 已到期	重新创建 Token
410	`TOKEN_REVOKED`	Token 已撤销	重新创建 Token
410	`TOKEN_VIEWS_EXHAUSTED`	访问次数已用完	创建新的 Token
410	`FILE_EXPIRED`	临时文件已过期	重新上传或创建预览
410	`FILE_DELETED`	文件已删除	重新上传文件