接口返回

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页面。

状态码 status 字段 说明
400 Bad Request 最常见的错误，通常是提供的参数（数量、类型）不符合要求，或者操作内容无效
400 ENCODING_ERROR 参数非UTF-8编码
400 DOWNLOAD_TIMEOUT 从网络获取图片超时。对应图片见字段 image 所反馈的值
400 DOWNLOAD_ERROR 网络地址图片获取失败。对应图片见字段 image 所反馈的值
400 IMAGE_FILE_SIZE_TOO_BIG 图片体积过大。对应图片见字段 image 所反馈的值
400 IMAGE_ID_NOT_EXIST 图片不存在。对应图片见字段 image 所反馈的值。
400 NO_FACE_DETECTED 图片未检测出人脸 。对应图片见字段 image 所反馈的值
400 CORRUPT_IMAGE 不是图片文件或已经损坏。对应图片见字段 image 所反馈的值
400 INVALID_IMAGE_FORMAT_OR_SIZE 图片大小或格式不符合要求。对应图片见字段 image 所反馈的值
400 INVALID_ARGUMENT 请求参数错误，具体原因见 reason 字段内容
401 UNAUTHORIZED 账号或密钥错误
401 KEY_EXPIRED 账号过期，具体情况见 reason 字段内容
403 RATE_LIMIT_EXCEEDED 调用频率超出限额
403 NO_PERMISSION 无调用权限
403 Forbidden 没有权限调用该 API，或者超过了调用限额
403 OUT_OF_QUOTA 调用次数超出限额
404 NOT_FOUND 请求路径错误
413 Request Entity Too Large 上传的文件过大
500 INTERNAL_ERROR 服务器内部错误

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 的功能时，您可以和商务部门联系，为您的账号开通权限。

results matching ""

    No results matching ""