绕口令与谜语查询：返回字段与 ret_code 全解（分页/错误码一文读懂）
# 绕口令与谜语查询：返回字段与 ret_code 全解（分页/错误码一文读懂）
**接口**：绕口令与谜语查询（apiCode=1623）· 接入点 1623-1 / 1623-2｜**是否免费**：免费（含使用档次限制）｜**返回格式**：JSON｜**适用人群**：已接入或准备接入的开发者｜**阅读时间**：约 6 分钟
## 核心要点
- 返回分两层：**系统级信封**（`showapi_res_code` 等）+ **业务体**（`showapi_res_body`，真正的数据在这里）。
- `ret_code` 仅两个语义：`"0"` 成功，非 `"0"` 失败（文档未给出非 0 的枚举清单，失败原因看 `showapi_res_error`）。
- 分页靠四个字段：`maxResult` / `allNum` / `allPages` / `currentPage`，两个接入点完全一致。
## Why：先搞懂返回，少踩坑
很多调用报错不是接口挂了，而是没分清「系统码」和「业务码」，或翻页时没读 `allPages`。这篇把两层结构和全部字段一次讲清，后续实战文章都引用它。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 业务数据位置 | 全部在 `showapi_res_body` 对象内 |
| 成功判定 | `showapi_res_body.ret_code == "0"` |
| 失败原因 | 系统级看 `showapi_res_error`；业务级非 0 时同样参考 `showapi_res_error` |
| 超时 | 绕口令 5s；谜语 15s |
## How：两级返回结构
### 第一层 · 系统级信封（每个接入点都一样）
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | integer | 系统级状态码（API 网关层） |
| `showapi_res_error` | string | 系统级错误信息，失败时非空 |
| `showapi_res_id` | string | 本次请求唯一标识，排查问题用 |
| `showapi_fee_num` | integer | 本次调用计费次数（免费接口也会计费计数） |
| `showapi_res_body` | object | 业务数据载体，见下 |
### 第二层 · 业务体 `showapi_res_body`（两接入点通用字段）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ret_code` | string | `0` | 业务状态码：`0` 成功，其余失败 |
| `contentlist` | array | `[...]` | 返回结果数组 |
| `maxResult` | string | `1000` | 当前页最大返回数 |
| `allNum` | string | `10` | 总条数 |
| `allPages` | string | `100` | 总页码数 |
| `currentPage` | string | `1` | 当前页码 |
### 接入点差异 · `contentlist` 子项
| 接入点 | 子项字段 | 含义 |
|------|------|------|
| 1623-1 绕口令 | `title` + `content` | 标题 + 绕口令内容 |
| 1623-2 谜语 | `question` + `answer` | 谜面 + 谜底 |
> 注意：`contentlist` 是**数组**，不是单对象；空结果时为空数组 `[]`，不要按 `null` 处理。
## 返回示例与解析
绕口令（1623-1）：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "67aed69ffb638c23e1f1cfd9",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": "0",
"contentlist": [
{ "title": "板凳与扁担", "content": "板凳宽，扁担长。扁担没有板凳宽，板凳没有扁担长。" }
],
"maxResult": "1000",
"allNum": "10",
"allPages": "100",
"currentPage": "1"
}
}
```
谜语（1623-2）：
```json
{
"showapi_res_body": {
"ret_code": "0",
"contentlist": [
{ "question": "“二儿故琢钉戏，了无遽容” （云南地名连民族2+2）", "answer": "昆明白族" }
],
"maxResult": "1000",
"allNum": "10",
"allPages": "100",
"currentPage": "1"
}
}
```
## 状态码速查（务必看清）
文档**只**给出：`ret_code` 为 `"0"` 表示成功，其余为失败。**没有提供非 0 的具体枚举值**。因此：
- 判断成功：`showapi_res_body.ret_code == "0"`。
- 失败时：**不要**去猜某个数字代表什么，直接读 `showapi_res_error` 文案；也别忘了看系统级 `showapi_res_code` / `showapi_res_error`。
- 常见失败来源：AppKey 无效/未开通、触发免费档位限制、网络超时（绕口令 5s/谜语 15s）。详见[错误处理与 ret_code 排查](https://www.showapi.com/guides/tongue-riddle-error-handling-1623)。
## 进阶 / 边界
- 分页第一页默认 `page=1`；要拿全部数据，从 1 循环到 `allPages`，配合 `allNum` 校验总数。见[分页遍历指南](https://www.showapi.com/guides/tongue-riddle-pagination-1623)。
- 免费接口有档次限制，`showapi_fee_num` 会累计计费次数；想省调用看[本地缓存策略](https://www.showapi.com/guides/tongue-riddle-cache-tier-1623)。
## FAQ
**Q1：为什么有两个 "code"？**
A：系统级 `showapi_res_code`（网关层）和业务级 `showapi_res_body.ret_code`（接口层）是两个层级，都可能出现非 0，失败排查两个都要看。
**Q2：ret_code 非 0 时有没有错误码表？**
A：文档未提供非 0 的具体枚举，失败原因统一看 `showapi_res_error` 文案，不要臆测具体数字含义。
**Q3：contentlist 为空是报错吗？**
A：不一定。关键词无匹配会返回空数组，此时 `ret_code` 仍可能是 `"0"`；建议用「数组长度 + ret_code」双重判断，而非只看 ret_code。
**Q4：allNum / allPages 是字符串还是数字？**
A：文档与示例中均为字符串（如 `"10"`、`"100"`），比较或运算前先转数字。
**Q5：maxResult=1000 代表一次能拉 1000 条吗？**
A：它是「当前页最大返回数」上限；实际单页返回约 10 条，要更多需翻页。
## 下一步阅读
- [绕口令与谜语查询：错误处理与 ret_code 排查](https://www.showapi.com/guides/tongue-riddle-error-handling-1623)
- [绕口令与谜语查询：绕口令关键词检索实战](https://www.showapi.com/guides/tongue-riddle-twister-query-1623)
- [绕口令与谜语查询：谜语关键词检索实战](https://www.showapi.com/guides/tongue-riddle-riddle-query-1623)
- **本系列共 12 篇**：查看[绕口令与谜语查询指南总目录](https://www.showapi.com/guides/tongue-riddle-guides-1623)
