开放接口服务规约与错误码说明

写在头里话

• 网关只是透传请求，进行协议的转换，不涉及具体的业务逻辑，so，业务接口使用问题需要找接口提供方（从服务中心中搜索），找网关答疑同学是无法解答该类问题的。
• 调用网关接口出错，请优先根据错误码自行排查问题，错误码请参考下文的说明，请仔细看一下错误信息，一般都能知道大致的原因。假如错误码是spInvokeErr，请优先找服务提供者排查问题

  服务返回规约

  应用服务通过网关对外开放服务时，服务返回内容必须严格遵守网关规范格式，你可以在网关控制台的服务配置中自定义自身服务和网关规范的字段映射关系，网关会根据你输入的字段名称从结果中尝试获取，所以：一定要匹配，一定要匹配，一定要匹配，否则网关无法正常返回结果。

  推荐的返回结构

  返回成功结构说明

  {
    success: true,
    content: 返回内容，{}/[]
  }

  返回失败结构说明

  {
    success: false,
    errorLevel:['info’, 'warn’, 'error’, 'fault’],
    errorCode:错误码,
    errorMsg:错误信息说明
  }

  网关失败时返回结构说明

  {
    "Code":"MissingParameter",
    "HostId":"u-api.alibaba-inc.com",
    "Message":"",
    "_RequestId":"",
    "errorCode":100,
    "errorLevel":"error",
    "errorMsg":"",
    "success":false
  }

  登录态失败时返回结构说明

  {
    "AccessToken":"",
    "IsAccess":false,
    "errorCode":1206,
    "errorLevel":"error",
    "errorMsg":"",
    "success":false
  }

  网关错误返回结构码说明

  Code错误码字段说明

  | 错误码 | 错误描述 | 解决方案 | | —- | :—-: | :—-: | | MissingParameter | 请求入参丢失 | 参考api文档的请求参数中必填列的说明 | | InvalidAPIKey | access_key不合法 | 请使用网关发布的应用access_key | | InvalidAPIKeyID.NotFound | access_key不存在 | 确认使用的access_key与应用环境是否匹配，区分日常与线上 | | InvalidAPI.NotFound | 访问的API服务不存在 | 确认访问的API服务名是否真实存在，一般服务名以/开头 | | Forbidden | 应用未开通服务的访问权限 | 需先订阅开通服务的访问权限 | | NoSuchVersion | 服务版本不匹配 | 从服务详情确认服务提供的版本号，默认1.0 | | SignatureNonceUsed | 相同请求短时间内重复拒绝 | 请确认客户端代码是否存在请求重复提交 | | UnsupportedOperation | 请求模式不匹配 | 从服务详情确认API服务接受的HTTP提交模式 | | SignatureDoesNotMatch | 签名结果不符合网关服务标准 | 先确认签名的secret_key是否正确，然后按照文档服务消费->代码开发章节的加签说明 | | FlowCtrlBanned | 服务触发限流后被禁用 | 等待禁用时间结束，服务会自动恢复 | | FlowCtrlHitMaxCount | 服务触发限流 | 服务在限流规则范围内达到请求最大阈值 | | SPParamMiss | 后端服务参数缺失 | 必须参数未配置为必填 | | spInvokeErr | 后端服务异常失败 | 网关往后端传递请求时失败 | | IpWhiteListValidate | 客户端IP不在服务设定白名单内 | 请确认客户端是否是合法范围内使用者 | | InvalidTimeStamp | 客户端时间戳非法 | 网关服务端最大接受客户端时间误差在15分钟 | | OauthInvokeError | sso登录态验证失败 | SSO验证登录态服务异常 | | SecurityValidate | http请求方式不匹配 | 更换请求方式POST/GET | | InvalidSPKeyID.NotFound | 后端应用服务未提供或者服务未开启 | 练下提供方检查应用服务是否被删除或下线 |

errorCode错误码字段说明

上述errorCode为网关占用错误码，业务系统建议数字型错误码5位数开始或用字符串型，如果业务应用错误码与系统保留雷同，网关会在业务错误码增加x-前缀后对外输出。

应用服务返回结果不符合规范的修改建议与示例

• 服务返回结果没有包装类，建议单独定义API，返回结果按格式规约进行包装。
• 服务返回结果已经包装，但是字段没有全部匹配，可以在网关控制台应用服务配置页面进行自行补充格式。举例说明
  如果应用服务返回的数据格式如下
  

  {
  "success":true,
      "data":{
      "success":true,
      "content":{},
      "errorLevel":"",
      "errorCode":"",
      "errorMsg":""
      },
  }

控制台上配置方法如下

如果应用服务返回的数据格式如下

{
    "isSuccess":true,
    "content":{},
    "code":"",
    "message":""
}

控制台上配置方法如下