图书ISBN查询错误码排查：ret_code 非 0 与"查不到"怎么办
# 图书ISBN查询错误码排查：ret_code 非 0 与"查不到"怎么办
> 接口/接入点：图书ISBN查询（1626-1） · 是否免费：免费 · 请求方式：POST / GET · 返回格式：JSON · 适用人群：开发者、运维 · 阅读时间：约 6 分钟
## TL;DR
- 两级成功标志都要判：系统级 `showapi_res_code=0` 且业务级 `ret_code=0` 才是真正成功。
- 业务级 `ret_code` 为 `0` 表示成功，**其他值表示调用失败/未找到**；`remark` 给出错误信息。
- 文档未提供完整错误码枚举，排查以"ISBN 是否合法 / 该书是否收录 / 服务是否维护"为主。
## Why
调用没返回书名时，新手常直接崩溃或误判"接口坏了"。其实失败原因很有限：号错了、书没收录、或临时服务维护。理清两级返回码与排查路径，能快速定位，减少工单与误报。
## What
| 字段 | 含义 | 处理 |
|------|------|------|
| `showapi_res_code` | 系统级（网关层） | 非 0 看 `showapi_res_error`，多为网络/服务层问题 |
| `ret_code`（业务体） | 业务级 | `0` 成功；**其他值=失败/未找到** |
| `remark` | 错误信息 | 成功为 `success`，失败时给出说明 |
> 说明：文档仅明确 `ret_code` 0=成功、其他=失败/未找到，**未给出完整枚举值**，因此不要臆造具体数字含义；以 `remark` 文本为准。
## How
### 步骤 1：分层判错
```python
import requests
APP_KEY = "YOUR_APPKEY"
def safe_lookup(isbn: str) -> dict:
resp = requests.post(
"https://route.showapi.com/1626-1",
params={"appKey": APP_KEY},
data={"isbn": isbn},
timeout=10,
).json()
if resp.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误：{resp.get('showapi_res_error')}")
body = resp["showapi_res_body"]
if body.get("ret_code") != 0:
# 失败/未找到：按 remark 处理，不视为异常
return {"found": False, "remark": body.get("remark")}
return {"found": True, "book": body["data"]}
```
### 步骤 2：按现象排查
| 现象 | 可能原因 | 排查动作 |
|------|---------|---------|
| `ret_code` 非 0，`remark` 提示未找到 | ISBN 错误 / 该书未收录 | 用 ISBN 格式校验篇做归一化与校验位自检 |
| `showapi_res_code` 非 0 | 服务维护/网络 | 看 `remark`，稍后重试（指数退避） |
| HTTP 超时 | 网络抖动 | 加重试与超时（默认 10s） |
| 返回字段为空 | 该书部分元数据缺失 | 展示端空值兜底（见避坑指南） |
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"remark": "success",
"data": { "title": "追风筝的人", "...": "..." }
}
}
```
失败示例：`ret_code` 非 0、`remark` 给出原因，`data` 缺失或为空，前端按"未找到"引导手动录入。
## 进阶 / 边界
- **不要编造错误码**：文档未给完整枚举，代码里不要写 `if ret_code == -3:` 之类未证实分支；统一用"非 0 即失败"处理。
- **重试策略**：仅对系统级/网络错误重试，且用指数退避；业务级"未找到"不要重试（号没变结果不变）。
- **超时设置**：默认 10s，结合 `timeout` 参数，避免线程长期阻塞。
## FAQ
**Q1：ret_code 等于哪些值分别代表什么？**
文档仅定义 0=成功、其他=失败/未找到，未提供完整枚举；以 `remark` 文本判断即可，不要假设具体数字。
**Q2：查不到是该书的错还是接口的错？**
多为 ISBN 不合法或该书未收录（业务级"未找到"），不是接口故障；先按格式校验篇自检。
**Q3：showapi_res_code 非 0 要重试吗？**
这是系统/网络层问题，可重试（指数退避）；但业务级"未找到"不要重试。
**Q4：为什么有时返回字段不全？**
部分图书元数据本身缺失（如 produce/paper 为空），属正常，展示端做空值兜底即可。
## 相关能力 / 下一步阅读
- [图书ISBN查询返回字段全解：一本书的 13 个元数据字段一文读懂](https://www.showapi.com/guides/isbn-book-fields-explained-1626)
- [图书ISBN查询实战：ISBN 格式识别与 978/10 位校验指南](https://www.showapi.com/guides/isbn-book-isbn-format-1626)
- [图书ISBN查询避坑指南：字段缺失、更新频率与免费档位限制](https://www.showapi.com/guides/isbn-book-best-practice-1626)
- **本系列共 12 篇**：查看[图书ISBN查询（apiCode=1626）官方指南总目录](https://www.showapi.com/guides/isbn-book-guides-1626)
