免费名言警句：常见问题与排查（ret_code 非 0 / 返回为空 / 免费档位限制）
# 免费名言警句：常见问题与排查（ret_code 非 0 / 返回为空 / 免费档位限制）
> 接口 1839-1 · 免费 · 适用人群：已接入、遇到报错的开发者 · 阅读时间：约 4 分钟
## 核心要点
- 先分两层判断：系统级 `showapi_res_code` 与业务级 `ret_code`，二者都正常才算成功。
- "返回为空"多因免费档位限制或参数/网络问题，而非接口故障。
- 接口真实参数只有 `num`，没有分类/作者/主题筛选——很多"筛不到"的困惑源于此。
## Why
接入后最容易卡在几类问题：调用报错、拿到空列表、想筛主题却做不到。这些问题大多是"没分清系统/业务层"或"对能力边界有误解"，并非接口坏了。本文把高频问题集中排查，帮你少走弯路。
## What
**排查顺序建议**
1. 看顶层 `showapi_res_code` 是否 `0`（系统层）。
2. 看 `showapi_res_body.ret_code` 是否 `"0"`（业务层），非 0 读 `remark`。
3. 确认 AppKey 正确、网络可达、未超免费档位。
## How：常见报错对照
| 现象 | 可能原因 | 处理 |
|------|---------|------|
| `showapi_res_code != 0` | 请求未被正常处理（鉴权/网络） | 检查 AppKey、URL、网络；看 `showapi_res_error` |
| `ret_code != "0"` | 业务失败 | 读 `remark` 文案定位；确认参数合法 |
| `contentlist` 为空 | 免费档位限制 / 临时无数据 | 核对档位；稍后重试或加缓存 |
| 想要某主题但取不到 | 接口无分类筛选参数（仅 `num`） | 见[num 参数篇](https://www.showapi.com/guides/famous-quotes-num-param-1839) |
## 返回示例与解析（错误样本）
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"contentlist": []
}
}
```
若 `ret_code=0` 却为空，优先怀疑免费档位限制，其次检查是否触发了频率/配额控制。
## 进阶 / 边界
- **免费档位限制是真实存在的**：注册后默认可用但有档次限制，超限可能表现为返回为空或错误提示，具体见[免费 API 页](https://www.showapi.com/free-api)。
- **不要对失败码重试**：业务层 `ret_code != "0"`（如参数/权限问题）重试无意义；仅对网络超时做指数退避。
- **`ret_code` 是字符串**：比较用 `"0"`，整数 `0` 比较会误判。
## FAQ
**Q1：提示"拒绝访问/无权限"怎么办？**
A：检查 AppKey 是否正确、是否已登录对应账号；确认请求地址 `route.showapi.com/1839-1` 与 `appKey` 匹配。
**Q2：为什么有时返回空列表？**
A：最常见是触达免费档位上限或频率限制；建议加缓存（见[缓存策略篇](https://www.showapi.com/guides/famous-quotes-cache-1839)）并控制调用频次。
**Q3：能不能按主题/作者筛选？**
A：不能，真实参数只有 `num`；需要主题化请在本地做分类匹配。
**Q4：`ret_code` 非 0 有哪些具体码？**
A：文档仅明确 `"0"` 为成功、其他为失败，未给完整失败码枚举；以 `remark` 文案为准排查。
**Q5：超时设多少？**
A：官方连接/读取超时均为 15 秒，客户端建议设 15 秒。
**Q6：返回中文乱码？**
A：响应为 UTF-8 JSON，确保解析库以 UTF-8 读取即可。
## 相关能力 / 下一步阅读
- [免费名言警句：返回字段全解（contentlist / ret_code / allNum）](https://www.showapi.com/guides/famous-quotes-response-fields-1839)
- [免费名言警句：如何设计缓存策略，避免重复调用浪费免费档位](https://www.showapi.com/guides/famous-quotes-cache-1839)
- [免费名言警句：num 参数怎么用？最多 10 条与"随机返回"机制](https://www.showapi.com/guides/famous-quotes-num-param-1839)
- **本系列共 10 篇**：查看[免费名言警句指南总目录](https://www.showapi.com/guides/famous-quotes-guides-1839)
