国际原油价格查询：ret_code 与常见调用错误排查
国际原油价格查询原油价格APIWTI原油布伦特原油免费接口 # 国际原油价格查询：ret_code 与常见调用错误排查
> 接口：国际原油价格查询（apiCode=1108，接入点 1108-1）｜ 免费 ｜ 请求方式 POST/GET ｜ 返回 JSON ｜ 适用人群：已接入、遇到调用异常的用户 ｜ 阅读时间：约 5 分钟
## 核心要点
- 成功判定唯一标准：`showapi_res_body.ret_code == 0`；非 0 即业务失败。
- 文档仅标注 `ret_code`「0 为成功，其他失败」，**未给出具体非零错误码枚举**，排查以现象+系统级字段为主。
- 常见失败多为 AppKey 问题、免费档位用尽、网络/超时，按清单逐项排查。
## Why
调用返回不对劲时，最该先问的是"是系统层错了还是业务层错了"。本接口用两层返回码：外层 `showapi_res_code` 看请求通不通，内层 `ret_code` 看业务成不成。本文给一张"先查什么后查什么"的排查清单，并如实说明文档没有给出具体非零错误码——不编造码值，避免你拿假码去对问题。
## What
| 项目 | 说明 |
|------|------|
| 业务成功 | `showapi_res_body.ret_code == 0` |
| 业务失败 | `ret_code != 0`（文档未枚举具体非零值） |
| 系统级 | 外层 `showapi_res_code` / `showapi_res_error` |
| 排查入口 | AppKey 管理、调用帮助、免费档位说明 |
## How
### 排查清单（按顺序）
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/1108-1"
try:
resp = requests.get(URL, params={"appKey": APP_KEY, "code": "wti"}, timeout=10)
resp.raise_for_status()
data = resp.json()
except requests.RequestException as e:
print("① 网络/超时层失败：", e) # DNS、连接、超时
raise
# ② 系统级：请求是否到达并处理
if data.get("showapi_res_code") != 0:
print("② 系统级异常 showapi_res_code =", data.get("showapi_res_code"),
"msg =", data.get("showapi_res_error"))
raise SystemExit("系统层失败")
# ③ 业务级：ret_code 是否成功
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
print("③ 业务失败 ret_code =", body.get("ret_code")) # 文档未给具体非零枚举，按现象排查
raise SystemExit("业务层失败")
print("成功：", body["nowPrice"], body["diff_rate"])
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
try {
const r = await fetch(
"https://route.showapi.com/1108-1?appKey=" + APP_KEY,
{
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: "code=wti",
signal: AbortSignal.timeout(10000),
}
);
const data = await r.json();
if (data.showapi_res_code !== 0) {
console.error("系统层失败", data.showapi_res_code, data.showapi_res_error);
process.exit(1);
}
if (data.showapi_res_body.ret_code !== 0) {
console.error("业务失败 ret_code =", data.showapi_res_body.ret_code);
process.exit(1);
}
console.log(data.showapi_res_body.nowPrice, data.showapi_res_body.diff_rate);
} catch (e) {
console.error("网络/超时层失败", e);
}
```
## 返回示例与解析
成功时 `ret_code == 0` 且 `showapi_res_body` 含完整字段；失败时 `ret_code != 0`。文档未提供具体非零 `ret_code` 的含义枚举，因此遇到非 0 时应结合 `showapi_res_error`（系统级）与控制台/档位状态判断，而非对照一份不存在的"错误码表"。
## 进阶 / 边界
- **不要臆造错误码对照**：本接口文档只说明 `ret_code`「0 成功、其他失败」，没有公布非零枚举；排查时以系统级 `showapi_res_error`、AppKey 状态、档位余量为准。
- **超时一定要设**：默认建议 10 秒，避免网络抖动时请求挂起。
- **档位用尽是常见坑**：免费接口有档次限制，频繁失败先查调用量是否触顶（见 [免费档位说明](https://www.showapi.com/free-api)）。
## FAQ
**Q：ret_code 非 0 时去哪查具体原因？**
文档未给出非零 ret_code 的枚举含义；建议先查系统级 `showapi_res_error`、再核对 AppKey 是否有效与免费档位是否用尽，必要时看调用帮助。
**Q：showapi_res_code 和 ret_code 都要判断吗？**
建议都判断：前者看请求是否到达/系统是否正常，后者看业务是否成功。两者为不同层级。
**Q：返回空数据或字段缺失怎么办？**
先确认 `ret_code == 0`；若成功但字段异常，核对 `code` 取值与返回结构（见返回字段全解），仍异常可提交工单。
**Q：免费档位用完了会报什么？**
文档未给出具体码值；表现为调用受限。优先降低频次并用缓存（见缓存策略指南），再查控制台档位状态。
## 相关能力 / 下一步阅读
- [国际原油价格查询返回字段全解：nowPrice / diff_rate / stockNum 一文读懂](https://www.showapi.com/guides/crude-oil-price-fields-1108)
- [国际原油价格查询：免费档位下如何设计缓存节省调用成本？](https://www.showapi.com/guides/crude-oil-price-cache-strategy-1108)
- [国际原油价格查询：5 分钟从注册到拿到第一条 WTI 报价](https://www.showapi.com/guides/crude-oil-price-quickstart-1108)
- **本系列共 12 篇**：查看[国际原油价格查询官方指南总目录](https://www.showapi.com/guides/crude-oil-price-guides-1108)
