错误码

错误码总表

所有接口统一返回 {code, msg, data} 信封，判断成功与否请看 code。本页按类别列出可能遇到的错误码、触发场景与处理建议。

10000 = 成功共 21 个错误码

客户端错误

状态码	含义	触发场景	处理建议
20001	参数缺失	必填参数没有传。	对照该接口「请求参数」表里标为必填的字段补齐后重试。
20002	参数格式错误	参数格式不对，比如该传数字却传了文字、JSON 体无法解析。	检查参数取值格式与请求体编码，并确认 Content-Type 与实际内容一致（JSON 用 application/json）。
20003	参数值非法	参数值本身不合法，比如超出取值范围、传入的 ID 不存在。	核对该参数文档里的取值说明后重新提交。
20010	未认证	请求没有携带认证信息。	按「签名说明」在请求头带上 APPID、时间戳与签名后重试。
20011	认证失败	签名校验不通过：密钥错误、参数被改动，或时间戳已过期。	用 APPSECRET 重新生成签名，确认时间戳在有效期内且参与签名的是原样参数。
20020	无权限	身份合法但无权访问：该接口仅限后台内部使用，或当前凭据无权执行该操作。	确认使用的是正确的账号 / 令牌；接口本身仅限后台内部使用的，请联系管理员。
20023	服务未开通	当前项目没有开通该服务（未命中任何启用中的项目授权；默认拒绝，新服务不会自动开放）。	联系管理员在控制台为该项目的 app_id 开通对应服务（服务级 / 线路级 / 接口级）。
20024	服务已过期	项目或该服务的授权已到期。	联系管理员续期后重试；返回的 data.valid_until 是不可用的到期时间。
20025	调用配额已用完	该服务在本周期（小时 / 天 / 月 / 累计）的调用次数已达上限。	按返回 data 里的 reset_at 等到下一周期再调用，或联系管理员提升配额。
20030	资源不存在	请求的路径不存在，或引用的资源不存在。	核对请求 URL 与资源 ID 是否正确。
20040	请求过于频繁	短时间请求过于频繁（例如登录连续失败被临时锁定）。	降低请求频率、稍后重试。
20041	请求方法不允许	使用了该接口不支持的 HTTP 方法。	按文档标注的方法（GET / POST 等）发起请求。

业务逻辑错误

状态码	含义	触发场景	处理建议
30001	业务规则限制	违反业务规则，例如当前账号状态不允许该操作。	按返回的 msg 提示处理；属于账号限制的请联系管理员。
30002	当前状态不允许此操作	对象当前状态不允许执行该操作。	按提示调整对象状态后再试。
30004	服务维护中	该服务正在维护，命中路径的请求被统一拦截。	稍后重试，或关注该服务的公告。
30005	服务已下线	该服务已下线。	改用其它可用服务或线路。
30006	服务开发中	该服务还在开发中，暂未对外开放。	等待服务上线后再调用。

第三方/外部服务错误

状态码	含义	触发场景	处理建议
40001	外部API调用失败	平台调用上游第三方服务失败（上游异常或网络问题）。	稍后重试；若持续失败请反馈，平台会排查上游链路。

系统内部错误

状态码	含义	触发场景	处理建议
50001	服务器内部错误	服务端发生未预期的内部异常。	稍后重试；若持续失败请反馈。
50002	服务暂不可用	服务暂时不可用（维护或过载）。	稍后重试。

未知错误

状态码	含义	触发场景	处理建议
99999	未知错误	发生了未归类的错误。	稍后重试；若持续失败请反馈。

遇到本页未列出的状态码，请连同请求参数与返回的 msg 一起反馈给我们。

小影API · 通用 API 聚合服务