文本关键词抽取：返回结构与 ret_code 状态码全解
# 文本关键词抽取：返回结构与 ret_code 状态码全解
- **接口 / 接入点**：文本关键词抽取（apiCode 941）· 接入点 `941-1`
- **是否免费**：是 ｜ **请求方式**：POST / GET ｜ **返回格式**：JSON
- **适用人群**：已接入的开发者、排查报错的用户
- **阅读时间**：约 6 分钟
## 核心要点
- 返回分两层：系统级（`showapi_res_code` / `showapi_res_error` / `showapi_res_id`）与业务级（`showapi_res_body` 内）。
- 业务是否成功，看 `showapi_res_body.ret_code == "0"`；`list` 才是关键词数组。
- 接口页未提供独立业务错误码表，系统级错误以公共返回参数为准。
## Why：为什么必须看懂返回结构
调用出错时，很多人分不清「网关报错」和「业务报错」，于是在参数上反复试错浪费时间。本文把每一层字段讲清楚，并给出判定顺序，让你一次定位问题。
## What：返回结构速览
| 层 | 字段 | 类型 | 说明 |
|----|------|------|------|
| 系统级 | `showapi_res_code` | Number | 网关状态码，0 成功 |
| 系统级 | `showapi_res_error` | String | 网关错误信息，成功为空 |
| 系统级 | `showapi_res_id` | String | 本次请求唯一标识 |
| 业务级 | `showapi_res_body` | Object | 业务数据容器 |
| 业务级 | `showapi_res_body.list` | Array | 关键词数组（字符串） |
| 业务级 | `showapi_res_body.ret_code` | String | 业务状态码，0 成功，其他失败 |
鉴权与公共返回参数（如签名错误、AppKey 无效等系统级错误）由 ShowAPI 公共返回参数承载，可在接口详情页「查看公共返回参数」了解。
## How：判定顺序
```python
import requests
def extract(text, appkey, num="10"):
r = requests.post("https://route.showapi.com/941-1",
data={"appKey": appkey, "text": text, "num": num}, timeout=10)
data = r.json()
# 1) 网关层
if data.get("showapi_res_code") != 0:
return f"网关错误：{data.get('showapi_res_error')}"
body = data.get("showapi_res_body", {})
# 2) 业务层
if str(body.get("ret_code")) != "0":
return f"业务失败 ret_code={body.get('ret_code')} err={data.get('showapi_res_error')}"
return body.get("list", [])
print(extract("这是一段测试的文字。", "YOUR_APPKEY"))
```
判定要点：
1. 先看 `showapi_res_code` 是否等于 0（网关层是否通）。
2. 再看 `showapi_res_body.ret_code` 是否等于 `"0"`（业务是否成功）。
3. 只有两层都成功，`list` 才是有效关键词。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"list": ["测试", "文字"],
"ret_code": "0"
}
}
```
> 说明：文档参数表里 `list` 的类型列标为 `String`，但描述为「所有的关键词数组」且示例中为字符串数组（如 `["测试","文字"]`），实际应按数组处理；公共文档类型标注疑似有误，以返回示例为准。
## 进阶 / 边界
- `ret_code` 与 `showapi_res_code` 含义不同：前者业务、后者网关，别只看一个。
- 页面返回示例里 `ret_code` 写作 `-1` 属示例占位，字段定义以「0 为成功，其他失败」为准。
- 本接口无独立业务错误码枚举；非 0 的 `ret_code` 结合 `showapi_res_error` 文本排查，必要时用 `showapi_res_id` 联系官方。
## FAQ
**Q1：showapi_res_code=0 但 ret_code 不是 0，算成功吗？**
A1：不算。网关通了但业务逻辑未通过（如参数被拦截），以 `ret_code != "0"` 视为失败，按 `showapi_res_error` 排查。
**Q2：list 字段类型到底是 String 还是 Array？**
A2：文档类型列写 String，但描述与示例都是数组，按数组（字符串列表）使用最稳妥。
**Q3：哪里看系统级错误码含义？**
A3：接口详情页提供「公共返回参数」，签名/AppKey 等系统级错误在那里定义；本接口页未单列业务错误码表。
**Q4：showapi_res_id 有什么用？**
A4：每次请求唯一标识，报错给官方排查时附上它，能快速定位那次调用。
**Q5：ret_code 返回 -1 是什么意思？**
A5：文档定义「0 成功，其他失败」，-1 属失败。具体原因看 `showapi_res_error`；示例中的 -1 是占位，不必照搬。
## 相关能力 / 下一步阅读
- [文本关键词抽取：5 分钟快速接入指南（Python / cURL / JS）](https://www.showapi.com/guides/text-keyword-quickstart-941) —— 先跑通再回来查结构
- [文本关键词抽取：免费接口下的缓存与限流策略（节省调用档位）](https://www.showapi.com/guides/text-keyword-cache-cost-941) —— 限流报错怎么兜底
- **本系列共 10 篇**：查看[文本关键词抽取指南总目录](https://www.showapi.com/guides/text-keyword-guides-941)
