车型大全常见问题与排查：ret_code 非0、必填缺失、brandId/serieId 怎么取
# 车型大全常见问题与排查：ret_code 非0、必填缺失、brandId/serieId 怎么取
> 接口/接入点：车型大全（apiCode 1467）· 全接入点 · 免费 · POST/GET · JSON · 适用人群：已接入用户、技术支持 · 阅读时间：约 6 分钟
## 核心要点
- 成功统一看 `showapi_res_body.ret_code == "0"`；非 0 即失败，结合 `msg` 判断原因，文档未给出非零错误码枚举表，不要对具体错误码做猜测性解读。
- 车型详情（1467-3）必填 `brandId` + `serieId`，二者缺一不可；`brandId` 来自品牌查询，`serieId` 来自车系查询。
- `brand_id`/`series_id`/`model_id` 是三级联动的"钥匙"，先查上级接入点再取 Id，不要凭名称硬猜。
## Why
接入车型大全时，绝大多数问题都集中在三件事：返回码怎么看、必填参数缺了怎么办、那几个 Id 从哪来。这篇做成可搜索的独立排查页，其他文章都链到这里，省得重复解释。
## What
| 现象 | 可能原因 | 排查方向 |
|------|----------|----------|
| `ret_code` 非 0 | AppKey 无效 / 触发档位限制 / 参数错误 | 看 `msg`；核对 AppKey；查免费档位 |
| 1467-3 失败 | 缺 `brandId` 或 `serieId` | 先跑 1467-1 取 brand_id，再跑 1467-2 取 series_id |
| 返回为空 | 入参品牌/车系不存在或拼写错 | 用 `brand_id`/`series_id` 入参，不用易错的中文名 |
| 数据不全 | 未翻页，`maxResults` 超 20 被拒 | `page` 递增翻页，单页 ≤20 |
## How
### 标准排查顺序（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
def call(path, params):
r = requests.post(f"https://route.showapi.com/{path}",
params={"appKey": APP_KEY, **params}, timeout=10)
r.encoding = "utf-8"
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
# 非 0 即失败：打印 msg 定位，不要假设具体错误码含义
raise RuntimeError(f"ret_code={body.get('ret_code')} msg={body.get('msg')}")
return body
# 1) 取 brand_id
brand = call("1467-1", {})["data"][0]
# 2) 取 series_id
serie = call("1467-2", {"brandId": brand["brand_id"]})["data"][0]
# 3) 用 brandId + serieId 查详情
detail = call("1467-3", {"brandId": brand["brand_id"], "serieId": serie["series_id"]})
print(detail["data"][0]["car_model"])
```
## 返回示例与解析
失败时返回形如 `{"showapi_res_body": {"ret_code": "非0", "msg": "提示信息", ...}}`。文档仅约定 `ret_code` `"0"` 为成功、其他为失败，未提供完整的非零错误码枚举，因此排查以 `msg` 为准。
## 进阶/边界
- 不要"猜"非零错误码含义——不同失败原因可能共用非 0 值，唯一可靠线索是 `msg`。
- Id 类字段（`brand_id`/`series_id`/`model_id`）会随数据更新变化，落库时以查询时的真实返回为准，不要硬编码旧 Id。
- 车型数据每周六 3 点更新，若"查不到刚发布的新车"属正常时效，非接口故障。
## FAQ
**Q: ret_code 返回非 0 代表什么？**
`"0"` 为成功，其他值表示失败。文档未提供非零错误码枚举表，请结合 `msg` 字段判断，常见为 AppKey 无效或触发档位限制。
**Q: 车型详情 1467-3 为什么要两个必填？**
`brandId` 与 `serieId` 共同定位一个车系，缺一不可。先用车系查询 1467-2 取 `series_id`，再连同 `brandId` 调用。
**Q: brand_id 和 series_id 从哪来？**
`brand_id` 来自品牌查询 1467-1 的 `data[].brand_id`；`series_id` 来自车系查询 1467-2 的 `data[].series_id`。
**Q: 为什么我的查询返回为空？**
多为入参品牌名拼写错或品牌/车系不存在。优先用 `brand_id`/`series_id` 入参，比中文名更稳定。
**Q: 一次最多返回多少条？**
车型详情 `maxResults` 最大 20 条，超出需 `page` 翻页；未翻页会漏数据。
## 相关能力 / 下一步阅读
- [车型大全：5 分钟接入，从注册到第一条品牌列表](https://www.showapi.com/guides/car-model-quickstart-1467)
- [车型大全三级联动查询实战：品牌→车系→车型详情全链路设计](https://www.showapi.com/guides/car-model-chain-query-1467)
- **本系列共 12 篇**：查看[车型大全 API 指南总目录](https://www.showapi.com/guides/car-model-guides-1467)
