接口返回

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.错误结果

当状态码为 4xx5xx 时,则意味着发生了错误,不同的状态码表示不同的错误类型。 消息体中的 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,或者超过了调用限额
404 NOT_FOUND 请求路径错误
413 Request Entity Too Large 上传的文件过大
500 INTERNAL_ERROR 服务器内部错误

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

5.参数错误示例

5.1 样例 : 缺少参数

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

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 ""