身份证归属地查询：错误处理与排错（showapi_res_code / ret_code 通用处理）
# 身份证归属地查询：错误处理与排错（showapi_res_code / ret_code 通用处理）
> 接口：身份证归属地查询（apiCode=25，接入点 25-3） · 免费 · POST/GET · JSON · 适用人群：所有开发者 · 阅读时间：约 6 分钟
## TL;DR
- 成功判断看两层：`showapi_res_code == 0` 且 `showapi_res_body.ret_code == 0`。
- **本接口文档未列出专用错误码枚举**，以下为基于 ShowAPI 公共返回结构的通用处理建议。
- 常见失败多来自鉴权缺失、网络/超时、号码为空或格式错——先查这些。
## Why
任何生产集成都要考虑"调用失败怎么办"。需要明确的是：**本接口官方文档只给出了成功态（`showapi_res_code:0`、`errNum:0`、`ret_code:0`、`retMsg:"success"`），并未列出该接口的专用错误码枚举**。因此本文不杜撰具体错误数字，而是给出基于公共返回结构的通用判错与排查路径，帮助你稳健地处理异常。
## What
| 层 | 字段 | 成功值 | 非成功时的含义 |
|----|------|--------|----------------|
| 系统级 | `showapi_res_code` | `0` | 非 0 多为网关/鉴权/平台级问题 |
| 系统级 | `showapi_res_error` | `""`(空) | 非空时为系统级错误描述 |
| 业务级 | `ret_code` | `0` | 非 0 为业务异常（具体枚举文档未给出） |
| 业务级 | `retMsg` | `success` | 非 success 时叠加业务消息 |
## How
### 步骤 1：两层判成功
```python
def safe_query(id_number: str) -> dict:
resp = requests.post(URL, params={"appKey": APP_KEY},
data={"id": id_number}, timeout=10)
resp.raise_for_status()
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误 {data.get('showapi_res_code')}: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(f"业务错误 {body.get('ret_code')}: {body.get('retMsg')}")
return body["retData"]
```
### 步骤 2：客户端侧排查（最常见）
- **鉴权**：路由必须带 `?appKey=`，缺失或无效会触发系统级错误。
- **网络/超时**：免费接口也受网络与平台频率约束，超时用退避重试（见 [批量核验](https://www.showapi.com/guides/idcard-attribution-batch-25)）。
- **参数为空/非法**：`id` 必填，空值或明显非法（长度≠18 等）先本地拦截，见 [调用前自检](https://www.showapi.com/guides/idcard-attribution-input-check-25)。
## 返回示例
成功返回见 [返回字段全解](https://www.showapi.com/guides/idcard-attribution-fields-25)；失败时外层/内层非 0，按上面两层提示排查。
## 进阶 / 边界
- **无专用错误枚举**：本文档未给出该接口的错误码表，遇到非 0 时以 `showapi_res_error` / `retMsg` 文本为准，不要假设具体数字。
- **降级策略**：接口不可用时，降级为"仅本地格式校验通过"，并记录日志、标记待补查，保障主流程不中断。
- **频率约束**：短时间内大量请求可能受限，配合 [Redis 缓存](https://www.showapi.com/guides/idcard-attribution-cache-25) 与限速降低风险。
## FAQ
**Q：文档里有这个接口的错误码表吗？**
没有。官方文档仅给出成功态（`showapi_res_code/errNum/ret_code = 0`、`retMsg: success`），未列出专用错误码枚举；异常时以 `showapi_res_error`/`retMsg` 文本信息为准。
**Q：返回非 0 我该查什么？**
先看 `showapi_res_code` 非 0 还是 `ret_code` 非 0：前者多在鉴权/网关层，后者在业务层；结合对应 `error`/`retMsg` 文本排查。
**Q：AppKey 不对会怎样？**
通常表现为系统级错误（鉴权失败）。确认 AppKey 已正确替换、未过期、且与接口权限匹配。
**Q：超时了怎么处理？**
设置合理 `timeout`（如 10s），失败用指数退避重试；高频场景加缓存与限速，见批量/缓存篇。
**Q：可以把错误码写死做分支吗？**
不建议。因文档未给该接口错误枚举，硬编码具体数字易随平台变动失效；以"成功/非成功"分支 + 文本信息为主更稳妥。
## 相关能力 / 下一步阅读
- [身份证归属地查询：返回字段全解（retData / address / birthday / sex 与系统级结构）](https://www.showapi.com/guides/idcard-attribution-fields-25)
- [身份证归属地查询：调用前如何先做身份证号格式与校验位合法性自检](https://www.showapi.com/guides/idcard-attribution-input-check-25)
- [身份证归属地查询：批量核验（Excel/CSV 导入）的循环调用设计](https://www.showapi.com/guides/idcard-attribution-batch-25)
- **本系列共 12 篇**：查看[身份证归属地查询指南总目录](https://www.showapi.com/guides/idcard-attribution-guides-25)
