行政区划查询状态码与错误码排查：ret_code / showapi_res_code 一文说清
# 行政区划查询状态码与错误码排查：ret_code / showapi_res_code 一文说清
> 接口 / 接入点：行政区划查询（apiCode 1149）· 区域查询 1149-1 / 子区域查询 1149-2 · 免费服务
> 请求方式：POST / GET · 返回格式：JSON · 适用人群：已接入开发者、排查问题用 · 阅读时间：约 5 分钟
## 核心要点
- 有两层状态码：`showapi_res_code`（系统级，0 成功）与 `showapi_res_body.ret_code`（业务级，0 成功），判断成功应两者都看。
- ⚠️ **官方文档未给出 `ret_code` 非零的具体错误码枚举**（如 -1 / -2 含义、参数缺失返回码均未列出）。
- 排查主线：先看系统级 `showapi_res_code`，再看必填参数（`areaName` / `parentId`）是否缺失或取错来源。
## Why：踩坑前先看懂状态码
调用返回一堆字段，哪一个是「真的成功」？只判断 `showapi_res_code` 会漏掉业务级失败（系统收到了请求，但业务没查到数据）。这篇把两层状态码关系和已知排查路径讲清，并**如实标注文档的盲区**，不编造错误码。
## What：两层状态码
| 字段 | 层级 | 已知取值 | 说明 |
|------|------|---------|------|
| showapi_res_code | 系统级 | 0 = 成功；非 0 = 系统/鉴权/网络层问题 | 所有 ShowAPI 接口通用 |
| showapi_res_error | 系统级 | 错误信息文本 | 失败时的描述 |
| ret_code | 业务级（在 showapi_res_body 内） | 0 = 成功 | 业务是否查到数据 |
| msg | 业务级 | 如「查询成功」 | 业务提示 |
> ⚠️ **需修正 / 标注项**：官方文档**未列出** `ret_code` 非零的具体枚举值（失败码含义、参数缺失返回码均未给出）。本文只列已观测 / 系统级情况，缺失部分以官方文档为准，不臆造数字。
## How：正确的成功判断
### Python（双层判断 + 容错）
```python
import requests
def safe_query():
r = requests.get("https://route.showapi.com/1149-1",
params={"appKey": "YOUR_APPKEY", "areaName": "昆明市", "level": "2"},
timeout=10)
try:
data = r.json()
except ValueError:
print("返回非 JSON，可能是网络/网关异常"); return
if data.get("showapi_res_code") != 0:
print("系统级错误:", data.get("showapi_res_error")); return
body = data.get("showapi_res_body", {})
rc = body.get("ret_code")
if str(rc) != "0": # ret_code 两接入点类型不一致，统一转字符串比
print("业务错误 ret_code=", rc, "msg=", body.get("msg")); return
print("成功:", [i["areaName"] for i in body.get("data", [])])
safe_query()
```
### cURL（看原始返回）
```bash
curl -X POST "https://route.showapi.com/1149-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "level=2&areaName=%E6%98%86%E6%98%8E%E5%B8%82&page=1"
```
### Node.js
```javascript
fetch(`https://route.showapi.com/1149-1?appKey=YOUR_APPKEY&level=2&areaName=` + encodeURIComponent("昆明市"))
.then(r => r.json())
.then(d => {
if (d.showapi_res_code !== 0) { console.error("系统级错误:", d.showapi_res_error); return; }
const body = d.showapi_res_body;
if (String(body.ret_code) !== "0") { console.error("业务错误:", body.msg); return; }
console.log("成功:", body.data.map(i => i.areaName));
});
```
## 返回示例（成功）
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": { "ret_code": 0, "msg": "查询成功", "data": [ {"areaName": "昆明市"} ] }
}
```
## 进阶 / 边界
- `ret_code` 两接入点类型不一致（区域查询为 Number，子区域查询为 String），比较前统一转字符串更稳。
- 文档未给失败码枚举：遇到非 0 的 `ret_code`，以 `msg` 文本 + 官方文档为准，不要凭经验猜数字含义。
- `showapi_res_code` 非 0 多半是鉴权 / 网络 / 参数格式问题，优先核对 AppKey 与请求方式。
## FAQ
**Q：ret_code 和 showapi_res_code 看哪个？**
两者都看：`showapi_res_code` 判断请求是否到平台并处理，`ret_code` 判断业务是否查到数据。
**Q：ret_code 非 0 代表什么错误？**
⚠️ 官方文档未给出 `ret_code` 非零的枚举含义，以返回 `msg` 文本及官方文档为准，本文不臆造错误码。
**Q：areaName / parentId 没传会返回什么？**
二者分别是两个接入点的必填项，缺失时业务层会返回错误（具体码以官方文档为准），`msg` 通常会提示参数问题。
**Q：ret_code 有时是数字有时是字符串？**
是。区域查询示例为 Number，子区域查询示例为 String，解析时做类型容错。
## 相关能力 / 下一步阅读
- [行政区划查询：5 分钟接入，从注册到第一条区划数据](https://www.showapi.com/guides/region-query-quickstart-1149)
- [行政区划查询返回字段全解：wholeName / 各级编码 / 拼音一文读懂](https://www.showapi.com/guides/region-query-response-fields-1149)
- **本系列共 11 篇**：查看[行政区划查询指南总目录](https://www.showapi.com/guides/region-query-guides-1149)
