数据接口调用失败或者没搜到结果，要扣钱吗？

用过积分制工具的团队大概都有这种体验：任务跑到一半失败了，积分照样扣掉。开发者为这个专门提过 issue，比如希望搜索请求失败时不要损失积分。下面把哪些扣费、哪些不扣费逐条列清楚。

逐种情况

发生了什么	返回码	扣费	要不要重试
key 错误或缺失	unauthorized	否	改好再试
参数不对	invalid_params	否	改好再试
余额不够这次调用	insufficient_balance	否	充值后再试
内容已删除、账号不公开	not_found	否	不要重试
请求太多	rate_limited	否	等 retry_after_seconds 后重试
平台或数据源故障	upstream_failed、upstream_busy	否	退避后重试
没有及时返回	timeout	暂时未知（null）	用同一个 Idempotency-Key 重试
搜索没有结果	ok，items 为空	是，按次价格	换关键词

背后的机制：调用发出前，先从余额里冻结这次最多可能花的钱。成功按实际价格扣，任何失败都把冻结的钱全部释放。这就是退款，当场完成。

真正会花钱的两种情况

• 结果为空。 一次什么都没搜到的小红书笔记搜索，仍然是完成的搜索：$0.02。新关键词先查一页，再决定翻不翻。
• 按条计费的搜索没有匹配。 公众号搜索按返回的账号数计费，至少按 1 个算：没有匹配也是 $0.058。

相反，查一条已删除的抖音视频返回 not_found，不收费。

留一份清楚的记录

import os, requests

H = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
body = requests.get("https://api.okdata.online/v1/douyin/videos/get", headers=H,
                    params={"url": "https://v.douyin.com/xxxxxx/"}, timeout=60).json()

if body["code"] == "ok":
    print("扣费", body["meta"]["billing"]["amount"], "余额", body["meta"]["billing"]["balance_after"])
else:
    print(body["code"], "charged:", body["charged"], "request_id:", body["request_id"])

遇到超时，用 GET https://api.okdata.online/v1/calls/{request_id} 查这次调用最后怎么结算的。

余额的退款

失败的调用根本不会从余额里扣走，所以没有什么要申请退回的。未使用余额的退款属于服务条款的内容，条款目前还是草稿；如果这一点影响你的采购决定，请发邮件问 hello@okdata.online。所有返回码的说明见错误码，价格见价格页。