# Am I charged when a data API call fails or finds nothing?

> Which social data API outcomes cost money: errors, deleted posts, timeouts, empty Xiaohongshu searches, per-item WeChat searches, and how failed calls are refunded.

Canonical page: https://okdata.online/answers/failed-api-calls-charged-refund/

**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](https://github.com/enginow-in/cortex/issues/209). 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](/apis/xiaohongshu/notes/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](/apis/wechat_mp/accounts/search/) is billed per account returned, at least one: $0.058 even when nothing matches.

A [Douyin video lookup](/apis/douyin/videos/get/) for a deleted video, on the other hand, is `not_found` and free.

## Keep a clean record

```python
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](/docs/errors/), and prices are on the [pricing page](/pricing/).

## Endpoints used

- [Xiaohongshu note search](https://okdata.online/apis/xiaohongshu/notes/search/) `xiaohongshu.notes.search`: $0.02 per call · about 20 notes per page
- [Official Account search](https://okdata.online/apis/wechat_mp/accounts/search/) `wechat_mp.accounts.search`: $0.058 per account · at most $0.58 per call
- [Douyin video detail](https://okdata.online/apis/douyin/videos/get/) `douyin.videos.get`: $0.002 per call

Updated 2026-11-12