有奖捉虫:云通信与企业服务文档专题,速来> HOT

云 API 3.0 接口默认返回 JSON 数据,返回非 JSON 格式的接口会在文档中做出说明。返回 JSON 数据时最大限制为 50 MB,如果返回的数据超过最大限制,请求会失败并返回内部错误。请根据接口文档中给出的过滤功能(例如时间范围)或者分页功能,控制返回数据不要过大。

注意:目前只要请求被服务端正常处理了,响应的 HTTP 状态码均为200。例如返回的消息体里的错误码是签名失败,但 HTTP 状态码是200,而不是401。

正确返回结果

以云服务器的接口查看实例状态列表 (DescribeInstancesStatus) 2017-03-12 版本为例,若调用成功,其可能的返回如下为:

    {
        "Response": {
            "TotalCount": 0,
            "InstanceStatusSet": [],
            "RequestId": "b5b41468-520d-4192-b42f-595cc34b6c1c"
        }
    }

  • Response 及其内部的 RequestId 是固定的字段,无论请求成功与否,只要 API 处理了,则必定会返回。
  • RequestId 用于一个 API 请求的唯一标识,如果 API 出现异常,可以联系我们,并提供该 ID 来解决问题。
  • 除了固定的字段外,其余均为具体接口定义的字段,不同的接口所返回的字段参见接口文档中的定义。此例中的 TotalCount 和 InstanceStatusSet 均为 DescribeInstancesStatus 接口定义的字段,由于调用请求的用户暂时还没有云服务器实例,因此 TotalCount 在此情况下的返回值为 0, InstanceStatusSet 列表为空。

错误返回结果

若调用失败,其返回值示例如下为:

    {
        "Response": {
            "Error": {
                "Code": "AuthFailure.SignatureFailure",
                "Message": "The provided credentials could not be validated. Please check your signature is correct."
            },
            "RequestId": "ed93f3cb-f35e-473f-b9f3-0d451b8b79c6"
        }
    }

  • Error 的出现代表着该请求调用失败。Error 字段连同其内部的 Code 和 Message 字段在调用失败时是必定返回的。
  • Code 表示具体出错的错误码,当请求出错时可以先根据该错误码在公共错误码和当前接口对应的错误码列表里面查找对应原因和解决方案。
  • Message 显示出了这个错误发生的具体原因,随着业务发展或体验优化,此文本可能会经常保持变更或更新,用户不应依赖这个返回值。
  • RequestId 用于一个 API 请求的唯一标识,如果 API 出现异常,可以联系我们,并提供该 ID 来解决问题。

公共错误码

返回结果中如果存在 Error 字段,则表示调用 API 接口失败。 Error 中的 Code 字段表示错误码,所有业务都可能出现的错误码为公共错误码。完整的错误码列表请参考本产品“API 文档”目录下的“错误码”页面。