API 返回处理

1.API 返回结构

返回结果（response）分为：状态码（status code）、头部（headers）、消息体（body）。其中算法的结果会以 JSON 格式放在消息体中。

如何从 HTTP 返回中分别获取这三部分信息，请参见所用 HTTP 库的文档。 解析 JSON 格式需要寻找所用语言的 JSON 库，参见 http://www.json.org/

2.正常结果

状态码为 2xx的为正常返回，最常见是 200。此时解析消息体中的 JSON 数据就可以获得本次 API 调用的结果。 JSON 中也会有一个 status 字段值为 OK表示正常返回。

返回示例

{
  "status": "OK"
  ......
}

3.错误结果

当状态码为 4xx 或 5xx 时，则意味着发生了错误，不同的状态码表示不同的错误类型。 消息体中的 JSON 数据包含了详尽的错误信息：status 字段中包含了错误类型描述， 如果还有更多错误信息则会在其他字段中提供。

收到 HTTP 返回后，一般先判断一下状态码，若属于错误则按需进行错误处理；部分 HTTP 库遇到属于错误的状态码后会抛出异常（Exception），这种情况下，直接处理异常即可。

HTTP 库遇错抛异常的情况，从异常对象中同样可以获得返回的状态码、头部和消息体，具体用法请查阅所用库的文档。

4.常见错误

每个 API 的调用公共错误在这里列出，而 API 特定的错误请查看对应的API页面。

404，413，5xx 这些类别的错误，HTTP 返回的消息体可能为空或者不是 JSON 格式， 请在解析 JSON 时注意处理解析错误。

5.参数错误示例

5.1 样例 : 缺少参数

每个 API 接受的参数包括参数名、 值类型、值范围、是否必需等。调用 API 时提供的参数不满足这些要求，就会出现无效参数错误： HTTP 状态码为 400，消息体 JSON 中 status 字段值为 INVALID_ARGUMENT， reason 字段给出更具体原因。

HTTP/1.1 400 Bad Request
Content-Length: 66
Content-Type: application/json

{
  "status": "INVALID_ARGUMENT",
  "reason": "must specify 'file' or 'url' argument",
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}

5.2 样例 : 超过调用限制

目前 Linkface 金融云 API 对调用频率有限制，每个用户的限制不同，每次 API 调用返回的头部中都包含频率限制的信息，例如：

HTTP/1.1 200 OK
Content-Length: 120
Content-Type: application/json
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 5

{
  "status": "OK”,
  ......
}

表示当前统计周期内总共限制 50 次调用，还剩余 7 次调用（意味着已经调用了 43 次）， 5 秒后将重置计数器进入下一统计周期。

一般只有发生调用频率超限错误时，才需要关注调用频率信息。错误样例：

HTTP/1.1 403 Forbidden
Content-Length: 30
Content-Type: application/json
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3

{
  "status": "RATE_LIMIT_EXCEEDED"
}

表明当前统计周期内已经超过调用频率限制，必须等待 3 秒后才能继续使用。

如果经常超过频率限制，可以申请提高限制以满足使用需求。

5.3 样例：无调用权限

系统对所有 API 的调用增加了限制，当您的账号调用了您权限以外的 API 时，系统会返回无调用权限的错误。

样例输出：

{
    "status": "NO_PERMISSION"
}

如果您需要用到这些 API 的功能时，您可以和商务部门联系，为您的账号开通权限。