Answers
Am I charged when a data API call fails or finds nothing?
Short answer
On okdata, a call that fails is never charged: bad parameters, deleted posts, rate limits and platform outages cost nothing, and the amount held for the call goes straight back to your balance. A search that succeeds but finds nothing is different: it is a completed call and costs the normal price, $0.02 for Xiaohongshu search. Test a new keyword on one page before paging.
Teams that have used credit-based tools know the feeling: a run fails halfway and the credits are gone anyway. Developers file issues about it, such as a request to stop losing credits when search requests fail. Here is exactly what is and is not billed.
Outcome by outcome
| What happened | Code | Charged | Retry? |
|---|---|---|---|
| Wrong or missing key | unauthorized |
no | after fixing |
| Bad parameter | invalid_params |
no | after fixing |
| Balance too low for this call | insufficient_balance |
no | after topping up |
| Post deleted, account private | not_found |
no | no |
| Too many requests | rate_limited |
no | yes, after retry_after_seconds |
| Platform or source down | upstream_failed, upstream_busy |
no | yes, with backoff |
| No answer in time | timeout |
not known yet (null) |
with the same Idempotency-Key |
| Search found nothing | ok, empty items |
yes, the call price | change the query |
Behind the table: before a call goes out, the most it can cost is held from your balance. On success the real price is charged; on any failure the whole hold is released. That is the refund, and it happens on the spot.
The two cases that do cost money
- Empty results. A Xiaohongshu note search that matches nothing is still a completed search: $0.02. Run one page of a new keyword before paging through it.
- Per-item search with no matches. Official Account search is billed per account returned, at least one: $0.058 even when nothing matches.
A Douyin video lookup for a deleted video, on the other hand, is not_found and free.
Keep a clean record
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("charged", body["meta"]["billing"]["amount"], "balance", body["meta"]["billing"]["balance_after"])
else:
print(body["code"], "charged:", body["charged"], "request_id:", body["request_id"])
For a timeout, look the call up at GET https://api.okdata.online/v1/calls/{request_id} to see how it settled.
Refunds of balance
Failed calls never leave your balance, so there is nothing to claim back. Refunds of unused balance belong to the terms of service, which are still a draft; ask hello@okdata.online if that matters for your purchase. Every code is explained on the errors page, and prices are on the pricing page.
Updated