汉字多功能转换器错误排查：showapi_res_code 与地址分词的 ret_code/msg
汉字多功能转换器汉字转拼音简繁转换全角半角地址分词 # 汉字多功能转换器错误排查：showapi_res_code 与地址分词的 ret_code/msg
> 接口/接入点：汉字多功能转换器（全部 6 个接入点） · 是否免费：是 · 返回格式：JSON · 适用人群：已接入开发者、运维 · 阅读时间：约 7 分钟
## 核心要点
- 所有接入点都有**系统级** `showapi_res_code`（int，0=成功），非 0 看 `showapi_res_error`。
- 地址分词额外有**业务级** `ret_code`（number，0=成功）与 `msg`，和其它接入点的 `data`/`flag` 不混用。
- 排查顺序固定：**先看系统级 → 再看业务级 → 最后核对参数名**。
## Why：为什么值得专门讲错误
这个接口把 6 种能力合一，错误表现也分两层：系统层（网络/鉴权/配额）和业务层（参数/内容）。最典型的坑是"用 `data`/`flag` 去解析地址分词"，结果取不到值以为是接口坏了。本文给出一张现象→字段→处理的对照表。
## What：两层错误模型
| 层级 | 字段 | 取值 | 位置 |
|------|------|------|------|
| 系统级 | `showapi_res_code` | 0=成功，非 0=失败 | 顶层 |
| 系统级 | `showapi_res_error` | 错误文案 | 顶层 |
| 业务级（仅地址分词） | `ret_code` | 0=成功 | `showapi_res_body` 内 |
| 业务级（仅地址分词） | `msg` | 错误提示，无错时不存在 | `showapi_res_body` 内 |
> 其它 5 个接入点（转拼音/简繁/全半角）没有 `ret_code`/`msg`，只用系统级 `showapi_res_code` + 业务 `flag`（字符串）。
## How：排查流程
**Python（统一判断骨架）**
```python
import requests
def call(point, **kw):
r = requests.post(f"https://route.showapi.com/{point}",
params={"appKey": "YOUR_APPKEY"},
data=kw, timeout=10).json()
# 第 1 层：系统级
if r.get("showapi_res_code") != 0:
return None, f"系统错误: {r.get('showapi_res_error')}"
body = r["showapi_res_body"]
# 第 2 层：地址分词业务级
if "ret_code" in body:
if body["ret_code"] != 0:
return None, f"业务错误: {body.get('msg')}"
return body.get("result"), None
# 第 3 层：其它接入点
if body.get("flag") != "true":
return None, "转换失败(flag != true)"
return body.get("data"), None
print(call("99-117", addr="云南省昆明市五华区学府路745号"))
print(call("99-38", content="你好"))
```
## 返回示例与解析
```json
// 地址分词业务失败示例
{ "showapi_res_code": 0, "showapi_res_body": { "ret_code": 1, "msg": "地址长度需大于4" } }
```
| 现象 | 可能原因 | 处理 |
|------|---------|------|
| `showapi_res_code` 非 0 | AppKey 错误/额度不足/网络异常 | 读 `showapi_res_error`，核对 AppKey 与档位 |
| 地址分词 `ret_code` 非 0 | `addr` 过短或格式异常 | 读 `msg`，保证 `addr` 长度 > 4 |
| 其它接入点 `flag` != "true" | 内容为空/不支持 | 检查 `content` 是否非空 |
| 解析 `data` 取到 None | 误用地址分词结构 | 地址分词读 `result`，不是 `data` |
## 进阶/边界
- 地址分词的 `msg` **无错时不存在**，代码用 `body.get("msg")` 而非 `body["msg"]`，避免 KeyError。
- 免费接口有档次限制，超限可能表现为系统级失败，需结合 `showapi_res_error` 与档位说明判断。
- `flag` 是字符串 `"true"`，比较请用 `== "true"`。
## FAQ
**Q1：showapi_res_code 和 ret_code 先判哪个？**
先判系统级 `showapi_res_code`，成功后再看业务级（地址分词的 `ret_code`）。
**Q2：为什么地址分词返回里没有 data？**
地址分词返回 `result`，不是 `data`；两套结构不可混用。
**Q3：msg 字段有时候没有？**
`msg` 仅在地址分词出错时出现，正常时该字段不存在。
**Q4：flag 是 true 但还是没数据？**
先确认 `showapi_res_code == 0`；若非 0 看 `showapi_res_error`。
## 相关能力 / 下一步阅读
- [汉字多功能转换器返回字段全解：data / simpleData / flag 与系统级 showapi_res_code](https://www.showapi.com/guides/hanzi-converter-response-fields-99)
- [汉字多功能转换器：地址分词实战（物流/地图场景的地址智能切分）](https://www.showapi.com/guides/hanzi-address-segment-99)
- [汉字多功能转换器免费额度与档次限制：如何避免调用被限流](https://www.showapi.com/guides/hanzi-converter-rate-limit-99)
- **本系列共 12 篇**：查看[汉字多功能转换器指南总目录](https://www.showapi.com/guides/hanzi-converter-guides-99)
