成语词典返回字段全解：showapi_res_body 与 ret_code 一文读懂
# 成语词典返回字段全解：showapi_res_body 与 ret_code 一文读懂
> 接口：成语词典（apiCode=2964） · 接入点：搜索成语(2964-1) / 成语详情(2964-2) / 随机成语(2964-3) · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：所有调用者 · 阅读时间：约 6 分钟
## 核心要点
- 所有接入点统一用 ShowAPI 包裹返回：系统级字段在顶层，业务数据在 `showapi_res_body`。
- 业务成功看 `showapi_res_body.ret_code == 0`；失败看 `remark` 提示。
- 三个接入点的业务字段差异很大（列表 vs 完整释义），本文用一张表并列说清。
## Why：为什么必须看懂返回结构
很多接入报错不是接口挂了，而是没分清「系统级返回」和「业务返回」：顶层 `showapi_res_code` 是 ShowAPI 网关状态，业务真正成不成功要看 `showapi_res_body.ret_code`。把两者混为一谈，就会在明明业务失败时报「成功」。本文把结构一次讲透，省去反复试错。
## What：统一返回包裹
| 顶层字段 | 类型 | 含义 |
|----------|------|------|
| `showapi_res_code` | Integer | API 网关状态码，0 通常表示请求被正常处理 |
| `showapi_res_error` | String | 网关级错误信息 |
| `showapi_res_id` | String | 本次请求唯一标识，排查用 |
| `showapi_fee_num` | Integer | 本次调用计费次数（免费服务预期为 0） |
| `showapi_res_body` | Object | 业务数据容器 |
`showapi_res_body` 内部：
| 字段 | 类型 | 含义 |
|------|------|------|
| `ret_code` | Number/String | 业务逻辑状态码：**0 为成功**，其他为失败 |
| `remark` | String | 业务提示信息（成功如「查询成功！」，失败给原因） |
> 注意：官方示例与 OpenAPI YAML 中 `ret_code` 在搜索/详情接入点标注为 Number、随机成语接入点标注为 String（文档内部类型标注不一致）。**实战中以「0 成功，其他失败」判断，不要依赖具体类型**。
## How：判断成功的标准写法
无论哪个接入点，统一这样判：
```python
body = data.get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败:", body.get("remark"))
else:
# 正常处理业务字段
...
```
```bash
# 网关层与业务层是两个层级，建议分别打印观察
curl -X POST "https://route.showapi.com/2964-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "keyword=画&page=1"
```
## 三个接入点业务字段对照
| 接入点 | 业务字段 | 说明 |
|--------|---------|------|
| 2964-1 搜索成语 | `list[]`(`id`,`word`)、`maxResult`、`currentPage`、`allNum`、`allPages` | 仅成语名+id，分页信息 |
| 2964-2 成语详情 | `word`、`pinyin`、`explain`、`derivation`、`sample` | 单条完整释义 |
| 2964-3 随机成语 | `word`、`pinyin`、`explain`、`derivation`、`sample` | 同详情，但无参数 |
> 关键差异：搜索返回的是**列表且不含释义**，详情/随机返回的是**单条完整释义**。要做「查词+展示解释」，必须 搜索 → 详情 两步，见[两步流指南](https://www.showapi.com/guides/idiom-search-detail-flow-2964)。
## 返回示例与解析
搜索（2964-1）返回：
```json
{
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"list": [{ "word": "守株待兔", "id": "b83eace0-ca55-4b0e-b85a-670d5604e1fc" }],
"maxResult": 20, "currentPage": 1, "allNum": 1, "allPages": 1
}
}
```
详情 / 随机（2964-2 / 2964-3）返回：
```json
{
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"word": "守株待兔",
"pinyin": "shǒu zhū dài tù",
"explain": "比喻死守经验，不知变通。",
"derivation": "《韩非子·五蠹》",
"sample": "凡事须主动，不可守株待兔。"
}
}
```
## 进阶 / 边界
- `showapi_fee_num` 为计费次数，免费服务下通常为 0；不要把它当成「剩余额度」。
- 文档未给出独立的业务错误码枚举（如 -2/-3 之类），失败时以 `remark` 文本为准，**不要自行臆造错误码**。
- 免费服务仍有频率约束，高频调用请看[免费与配额说明](https://www.showapi.com/guides/idiom-free-api-cost-2964)与[缓存策略](https://www.showapi.com/guides/idiom-pagination-cache-2964)。
## FAQ
**Q：showapi_res_code 和 ret_code 有什么区别？**
前者是 ShowAPI 网关层状态，后者是业务层状态。接入判断以 `showapi_res_body.ret_code` 为准。
**Q：ret_code 等于 0 就一定能拿到数据吗？**
绝大部分情况能，但仍要检查业务字段是否存在（如搜索可能 allNum 为 0，list 为空）。
**Q：返回里没有 error 字段怎么办？**
失败时信息在 `showapi_res_body.remark`，不在顶层。
**Q：免费接口的 fee_num 一直为 0 正常吗？**
正常，免费服务不计费或计为 0。
## 相关能力 / 下一步阅读
- [成语词典三大接入点怎么选：搜索 / 详情 / 随机一篇说清](https://www.showapi.com/guides/idiom-dictionary-access-points-2964)
- [成语词典：从搜索到释义的两步流，搭建查词功能](https://www.showapi.com/guides/idiom-search-detail-flow-2964)
- [成语词典是免费服务意味着什么？showapi_fee_num 与配额说明](https://www.showapi.com/guides/idiom-free-api-cost-2964)
- **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)
