公共错误定义¶
以下错误适用于 External API 的通用鉴权和请求处理。接口自身的业务错误见各接口页。
| HTTP 状态 | errorCode | 触发条件与处理 |
|---|---|---|
| 400 | ft.InvalidNonce | 缺少 nonce 或重复使用。每次重试使用新的 nonce,并重新签名。 |
| 400 | ft.MissingAuthHeaderInfo | 缺少 Access Key、签名或时间戳。检查签名请求头。 |
| 400 | ft.IllegalTimestamp | 时间戳超出配置允许的偏差。同步客户端时钟,使用 Unix 秒并重新签名。 |
| 403 | ft.CrosssValidateFailed | 签名不匹配。检查签名版本、原始请求路径、查询字符串和签名原文。 |
| 403 | ft.Forbidden | 签名账号权限不足。检查接口需要的读写权限。 |
| 404 | ft.InvalidAccessKey | Access Key 无效。检查调用的站点和平台账号配置。 |
| 404 | ft.NotFoundAkSkCfg | 服务未找到 External API 签名账号配置。联系服务管理员。 |
| 406 | ft.ParameterValidationFailed | 参数违反声明的字段限制。按 message 中的字段和规则修正请求。 |
| 400 | ft.RequestJsonFormatError | JSON 语法错误。使用 content.reason、line 和 column 定位。 |
| 429 | ft.ApiMultiEntryRateLimited | 接口命中已配置的限流组。根据 Retry-After(如有)退避,并使用新 nonce 重新签名。 |
| 503 | ft.ApiMultiEntryRateLimitUnavailable | 适用的限流服务暂不可用。稍后重试。 |
| 500 | ft.InternalServerError | 内部错误。保存响应中的 traceId 以便排查。 |
message 可能随语言或字段上下文变化。客户端可使用 HTTP 状态和 errorCode 分支处理。