科学计算器返回字段全解：ret_code / result / remark 一文读懂
# 科学计算器返回字段全解：ret_code / result / remark 一文读懂
> 接口 免费科学计算器（apiCode 1699）· 接入点 科学计算器（1699-1）· 免费 · POST/GET · 返回 JSON · 适合 已接入 / 调试中的开发者 · 阅读约 4 分钟
## 核心要点
- 业务数据全部在 `showapi_res_body` 对象里，核心三字段：`ret_code`、`result`、`remark`。
- `ret_code` 是业务成败标志：`0` 成功（计费），`-1` 失败（不计费，如网络/超时/方法出错）。
- 系统级字段（`showapi_res_code` / `showapi_res_id` / `showapi_fee_num`）用于请求追踪与计费核对，不参与业务判断。
## Why：为什么必须看懂返回结构
接入任何 API，第一步都是「怎么判断成功、失败时长什么样、结果在哪」。科学计算器的返回结构很规整，但有两个细节容易踩坑：① `ret_code` 和 `showapi_res_code` 是两个不同层级的状态码；② 失败时 `result` 为 `null`。本篇把它们彻底讲清，让你写判断逻辑时一次写对。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 请求地址 | `https://route.showapi.com/1699-1?appKey={your_appKey}` |
| 返回格式 | JSON（业务数据在 `showapi_res_body` 内） |
| 计费 | 免费，[使用档次限制](https://www.showapi.com/free-api) |
## How：返回结构拆解
一次成功调用（`num=5&operation=factorial`）的真实返回（实测）：
```json
{
"showapi_res_error": "",
"showapi_res_id": "6a991176fb638c8138ea8825",
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": 0,
"remark": "成功",
"result": 120.0
}
}
```
### 业务级字段（`showapi_res_body` 内）
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | String/Number | 业务成败：`0`=成功（扣费 1 次）、`-1`=失败（不扣费）。失败时通常伴随方法错误 |
| `result` | Number | 计算结果。成功时有值；失败时通常为 `null` |
| `remark` | String | 文字说明：成功为「成功」，失败为「方法调用出错」「operation不能为空或者不正确」等 |
### 系统级字段（与 `showapi_res_body` 同级）
| 字段 | 说明 |
|------|------|
| `showapi_res_code` | 整次 HTTP 请求的状态码，正常为 `0` |
| `showapi_res_error` | 系统级错误文案，正常为空字符串 |
| `showapi_res_id` | 请求追踪 ID，排查问题时给客服报这个 |
| `showapi_fee_num` | 本次计费次数，免费额度内为 `1` |
### 判断逻辑（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
r = requests.post(
"https://route.showapi.com/1699-1",
params={"appKey": APP_KEY},
data={"num": "5", "operation": "factorial", "rad_or_ang": ""},
timeout=10
)
body = r.json()["showapi_res_body"]
if str(body.get("ret_code")) == "0":
value = float(body["result"]) # 120.0
print("结果:", value)
else:
print("失败原因:", body.get("remark"))
```
## 返回示例与解析
| 场景 | `ret_code` | `result` | `remark` | 说明 |
|------|-----------|----------|----------|------|
| 正常 | `0` | `120.0` | 成功 | 阶乘(5)=120 |
| 方法出错 | `-1` | `null` | 方法调用出错 | 如暂不可用的 `subtraction` / `percentage` |
| 操作名写错 | `-1` | `null` | operation不能为空或者不正确 | `operation` 不在 32 个合法名内 |
> `ret_code` 在文档里标注为 String，但实测返回是数字 `0`；判断时建议用 `str(...) == "0"` 同时兼容两种类型。
## 进阶 / 边界
- **失败一定有 `remark` 文案**：把它透传给前端或日志，能直接定位问题，不用自己猜。
- **`result` 是浮点数值**：连乘、开方等结果可能是 `24.0`、`1.08006` 这种，展示前按需格式化。
- **浮点误差**：三角函数会带浮点尾差，如 `sin(30°, ang)=0.49999999999999994`，展示时建议四舍五入。
## FAQ
**Q1：`ret_code` 和 `showapi_res_code` 有什么区别？**
`showapi_res_code` 是整次请求的系统状态（网络/网关层），`ret_code` 是业务计算结果状态。看业务成败看 `ret_code` 即可。
**Q2：失败时 `result` 是什么？**
通常为 `null`（JSON 里是 `None`）。务必先判 `ret_code` 再读 `result`，避免空值报错。
**Q3：`-1` 一定是不扣费吗？**
是。文档明确 `-1` 表示渠道失败（如网络失败、超时），不扣费。
**Q4：`showapi_fee_num` 每次都是 1 吗？**
免费接口每次成功调用计 1 次额度，正常就是 `1`；异常/失败时不会出现或不计费。
**Q5：怎么排查一次失败的调用？**
先看 `remark` 文案：是「方法调用出错」还是「operation不能为空或者不正确」，对照[错误码排查](https://www.showapi.com/guides/calculator-error-codes-1699)定位。
**Q6：返回里的 `result` 精度够科研用吗？**
接口定位是「较为可靠的精度和准确度」，日常计算、教学、工程估算足够；极端高精度科研场景建议本地高精度库复核关键结果。
## 相关能力 / 下一步阅读
- [科学计算器错误码排查](https://www.showapi.com/guides/calculator-error-codes-1699) —— `ret_code -1` 各类文案与排查
- [科学计算器：5 分钟接入](https://www.showapi.com/guides/calculator-quickstart-1699) —— 第一次调用从这里开始
- [科学计算器已知问题与使用避坑](https://www.showapi.com/guides/calculator-known-issues-1699) —— 官方文档没写的几个坑
- **本系列共 11 篇**：查看[科学计算器开发指南总目录](https://www.showapi.com/guides/calculator-guides-1699)
