---
title: "错误 · 文档 · SocialToAI"
canonical: https://socialtoai.app/zh/docs/api/errors/
updated: 2026-11-20
---

# 错误

SocialToAI 一共有 19 个错误代码，全都不扣费。执行前被拒绝的请求返回 HTTP 错误状态码；平台那边的失败仍是 HTTP 200，错误写在返回体里。每个错误都带 request_id 和 fix，后者说明怎么改正。

- 页面：https://socialtoai.app/zh/docs/api/errors/
- 最近更新：2026-11-20

## 全部代码

| 代码 | HTTP | 发生了什么，怎么办 | 重试 | 扣费 |
| --- | --- | --- | --- | --- |
| `invalid_params` | 400 | 缺少参数，或参数不对。 没有执行。按返回里的 `fix` 改正。 | 不用 | 不扣 |
| `not_supported` | 400 | 这个平台没有这个动作。 `fix.allowed` 列出了支持的平台。 | 不用 | 不扣 |
| `unauthorized` | 401 | Key 缺失、不对、已到期或被暂停。 在请求头里带上有效的 Key；`reason` 说明是哪种情况。 | 不用 | 不扣 |
| `insufficient_balance` | 402 | 余额不够这次调用。 没有执行。购买积分后再发一次。 | 不用 | 不扣 |
| `max_cost_exceeded` | 402 | 这次调用超过了你给的 `max_cost_credits`。 没有执行。`quote_credits` 是它需要的积分。 | 不用 | 不扣 |
| `plan_limit` | 403 | 免费账户能做的已经到头：可发起的调用用完了，批量在首次购买后才开放，或它已经有 1 个定期运行（监控）。 没有执行。购买积分后继续。 | 不用 | 不扣 |
| `key_scope_denied` | 403 | 这把 Key 没有这项权限。 在这把 Key 的设置里打开对应权限。 | 不用 | 不扣 |
| `not_found` | 200 / 404 | 内容或账号不存在、是私密的，或已删除；平台说了原因时 `why` 写明是哪一种，`platform_says` 是平台的原话。来源对这次查询照常收费的接口按价扣费，报错带 `charged: true`。 不用重试。路径写错时也返回这个代码。 | 不用 | 来源收费时按价扣 |
| `idempotency_in_progress` | 409 | 同一个 `Idempotency-Key` 的调用还在进行。 等 `Retry-After` 之后用同一个键再问。 | 可以 | 不扣 |
| `handle_expired` | 410 | 保存的结果已过期。 重新发起这次调用。 | 不用 | 不扣 |
| `idempotency_conflict` | 422 | 这个 `Idempotency-Key` 已经用在另一组参数上。 不同的请求换一个新的键。 | 不用 | 不扣 |
| `daily_limit_reached` | 429 | 每日上限已到。 没有执行。上限设在 Key 或账户上，到 `resets_at` 重新开始。 | 不用 | 不扣 |
| `free_failure_limit` | 429 | 短时间内失败的调用太多。 等到 `retry_at` 再发。 | 可以 | 不扣 |
| `rate_limited` | 429 | 这把 Key 每秒调用太多，或同时在跑的太多。 等 `Retry-After` 之后再发。 | 可以 | 不扣 |
| `internal_error` | 500 | 运行超时被中止，没有扣费，可以再运行一次。 | 可以 | 不扣 |
| `temporarily_unavailable` | 200 / 503 | 这个调用暂时停用。 状态页会说明原因，稍后再试。 | 可以 | 不扣 |
| `invalid_target` | 200 | 链接或编号指向的目标无效。 检查 `fix.param` 指出的那个值。 | 不用 | 来源收费时按价扣 |
| `upstream_error` | 200 | 这次没有从平台取到结果，我们这边已经试过最多三次。 `retryable` 为 true 时，等 `retry_after_seconds` 秒再发一次；同一个请求又失败，多半是内容本身取不到，换一个输入。 | 视情况 | 不扣 |
| `timeout` | 200 | 没有按时拿到结果，也无法确定是否执行过。成本由我们承担。 我们不会自动重试（`X-Should-Retry: false`）。还需要的话请发起新请求。 | 不用 | 不扣 |

## 逐个代码看

下面的文字就是 API 返回的原话，`fix` 是随它一起返回的内容示例。

### `invalid_params` (HTTP 400, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 请求体必须是一个 JSON 对象。 | `{"param":"platform"}` |
| – | query 必须是 1 到 500 个字符的文字。 | `{"param":"query"}` |
| – | limit 必须是 1 到 50 的整数。 | `{"param":"limit"}` |
| – | 缺少 platform。 | `{"param":"platform","allowed":["tiktok","instagram","x"]}` |
| – | 这个调用不收参数 lang。 | `{"param":"lang","allowed":["query","sort"]}` |
| – | query 必须是非空的字符串或整数。 | `{"param":"query"}` |
| – | 这个平台的 sort 只能是 relevance、latest，本次没有扣费。 | `{"param":"sort","allowed":["relevance","latest"]}` |
| – | 缺少 query。 | `{"param":"query"}` |
| – | since 必须是 ISO 8601 日期（2026-10-01）或时间（2026-10-01T08:00:00Z），本次没有扣费。 | `{"param":"since"}` |
| – | since 不能晚于现在，也不能晚于 until，本次没有扣费。 | `{"param":"since"}` |
| – | id、url 里必须给且只给一个。 | `{"param":"id","allowed":["id","url"]}` |
| – | id、url 里只能有一个是列表。 | `{"param":"url","note":"Each value of the list is fetched and charged as a call of its own."}` |
| – | 一次请求最多 20 个平台或目标。 | `{"param":"platform","note":"Send at most 20 at a time."}` |
| – | 这个请求按 limit 要取的页数合计超过 40 页，本次没有扣费。 | `{"param":"limit","note":"Ask for fewer items or fewer platforms, or go on from page.cursor in a next request."}` |
| – | 这个调用不提供 include 的 comments，本次没有扣费。 | `{"param":"include","allowed":[]}` |
| – | Idempotency-Key 必须是 1 到 255 个可见 ASCII 字符。 | `{"param":"Idempotency-Key"}` |
| – | cursor 无效、不属于这个请求或已过期，本次没有扣费。 | `{"param":"cursor","note":"Send the request again without cursor to start from the first page."}` |
| – | max_cost_credits 必须是不小于 0 的整数。 | `{"param":"max_cost_credits"}` |
| – | format 只能是 json、csv 或 ndjson。 | `{"param":"format","allowed":["json","csv","ndjson"]}` |
| – | 数据来源不接受 query 的这个取值，本次没有扣费。 | `{"param":"query","note":"What the source says is wrong: query must be at most 100 characters. Change query and send the request again."}` |
| – | window 的值不对，本次没有扣费。 | `{"param":"window","allowed":["7d","30d"]}` |
| – | platforms 最多 5 个，本次没有扣费。 | `{"param":"platforms","note":"Send at most 5."}` |
| – | targets 里有认不出是哪个平台的链接，本次没有扣费。 | `{"param":"targets","note":"Give the whole link to the post or to the account page, as the platform shows it."}` |
| – | targets 里有读不出是哪条帖子的链接（短链，或不是帖子页），本次没有扣费。 | `{"param":"targets","note":"Give the whole link to the post, as the platform shows it in the address bar."}` |
| – | accounts 里有读不出是哪个账号的链接（短链，或不是主页），本次没有扣费。 | `{"param":"accounts","note":"Give the whole link to the account's page, as the platform shows it in the address bar."}` |
| – | 这个预览已过期，本次没有扣费。 | `{"param":"token","note":"Call watch with action=preview again, show the user the new preview, and confirm with its token."}` |
| – | 每个账户最多 20 个定时，本次没有扣费。 | `{"note":"Delete a schedule that is no longer needed, then make this one."}` |
| – | push_url 不是飞书、企业微信或 Slack 群机器人的 Webhook 地址，本次没有扣费。 | `{"param":"push_url","allowed":["https://open.feishu.cn/open-apis/bot/v2/hook/… (or open.larksuite.com)","https://qyapi.weixin.qq.com/cgi-bin/webhook/send?… (the group bot's own address, whole)","https://hooks.slack.com/services/…"],"note":"Copy the address from the group bot's settings in the chat, whole."}` |
| – | 这个群机器人没有收下测试消息，没有保存，本次没有扣费。 | `{"param":"push_url","note":"Check that the bot is still in the chat and the address was copied whole. A Feishu bot with a signature check or an IP allowlist refuses us: switch those off, or set the keyword SocialToAI instead."}` |
| – | b23.tv 短链要打开才知道是哪个视频，这里不展开短链：在浏览器里打开它，传地址栏里 bilibili.com/video/BV… 的完整链接，或直接传 BV 号。本次没有扣费。 | `{"param":"url","note":"Pass id: \"BV1…\", or url: \"https://www.bilibili.com/video/BV1…\"."}` |
| – | 查询参数 range 不对，本次没有扣费。 | `{"param":"range","note":"Correct the query parameter named here and send the request again."}` |
| – | 请求体读不出来，本次没有扣费。 | `{"note":"Send one JSON object with Content-Type: application/json."}` |
| – | 请求体太大，本次没有扣费。 | `{"note":"Send fewer targets in one request."}` |

### `not_supported` (HTTP 400, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| `no_such_capability` | 这个平台没有 search。 | `{"param":"platform","allowed":["tiktok","instagram","x"]}` |
| `not_available_yet` | 这个平台的 search 暂未提供，本次没有扣费。 | `{"param":"platform","allowed":["tiktok","instagram","x"]}` |
| `no_such_capability` | 目录里没有 tiktok.name，本次没有扣费。 | `{"param":"op","allowed":[],"note":"POST /v1/find finds an op by what it does; GET /v1/capabilities lists them all."}` |
| `not_available_yet` | tiktok.name 暂未提供，本次没有扣费。 | `{"param":"op","allowed":[],"note":"GET /v1/capabilities lists what can be called now."}` |
| `no_such_capability` | 这个平台的 search 没有 type 的这个取值，本次没有扣费。 | `{"param":"type","note":"Leave type out, or give another value."}` |
| `not_available_yet` | 这个平台的 search 暂未提供 sort 的这个取值，本次没有扣费。 | `{"param":"sort","note":"Leave sort out, or give another value."}` |
| – | 这里暂时不能推送到群聊，本次没有扣费。 | `{"param":"push_url","note":"Use email or a webhook instead."}` |
| `not_available_yet` | brand_buzz 现在不能在 tiktok 上运行，本次没有扣费。 | `{"allowed":["tiktok","instagram","x"],"note":"Use one of the platforms it runs on now."}` |
| `not_available_yet` | brand_buzz 不提供这个规模的运行，本次没有扣费。 | `{"param":"scale","allowed":["small"],"note":"Use a smaller scale, or fewer platforms or targets."}` |
| `not_available_yet` | brand_buzz 的这次运行暂未提供，本次没有扣费。 | `{"param":"confirm","note":"Send confirm: false for the plan of this request and its price. A smaller scale may run where this one does not."}` |

### `unauthorized` (HTTP 401, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| `missing` | Key 缺失、粘贴不完整或不存在，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/keys/","note":"No account yet? Sign up at https://socialtoai.app/sign-in/: 100 free credits, no card. A client that signs in with OAuth (ChatGPT, Claude, Claude Code, Codex, Cursor) needs no key: connect it to https://socialtoai.app/mcp and sign in. Otherwise create a key at https://socialtoai.app/console/keys/ and send it as Authorization: Bearer <key> or X-API-Key: <key>; keep it in the environment variable SOCIALTOAI_API_KEY. GET /v1/capabilities and POST /v1/find need none."}` |
| `invalid` | Key 缺失、粘贴不完整或不存在，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/keys/","note":"Send a current key as Authorization: Bearer <key> or X-API-Key: <key>; keep it in the environment variable SOCIALTOAI_API_KEY. Create one at https://socialtoai.app/console/keys/ (signing up gives free credits); GET /v1/capabilities and POST /v1/find need none."}` |
| `key_in_query` | 这个地址不收网址里的 Key；这把 Key 已经暴露，请撤销并新建一把，放在请求头里。本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/","note":"Send the key as Authorization: Bearer <key> or X-API-Key: <key>."}` |
| `suspended` | 这个账户已被暂停，本次没有扣费。 | `{"note":"Write to support@socialtoai.app."}` |
| `expired` | 这把 Key 已到期，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/","note":"Its owner can set a later expiry, or create a new key."}` |
| – | 需要有效的登录会话。 | `{"action_url":"https://socialtoai.app/sign-in/","note":"Sign in again."}` |
| `revoked` | 这把 Key 已被撤销，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/","note":"Create a new key."}` |
| `suspended` | 这把 Key 已被支持团队暂停，本次没有扣费。 | `{"note":"Write to support@socialtoai.app."}` |

### `insufficient_balance` (HTTP 402, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 余额不足，本次需要 10 积分，没有扣费。 | `{"action_url":"https://socialtoai.app/console/billing/","note":"Buy credits, then send the same request again."}` |

### `max_cost_exceeded` (HTTP 402, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 本次需要 10 积分，超过了 max_cost_credits，没有扣费。 | `{"param":"max_cost_credits","note":"Send max_cost_credits of at least 10, or leave it out."}` |

### `plan_limit` (HTTP 403, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这个免费账户能发起的调用已经用完，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/billing/","note":"Buy credits to keep calling."}` |
| – | 免费账户可以保留 1 个定时（监控），本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/billing/","note":"Delete the one it has, or buy credits: a paid account keeps up to 20."}` |
| – | brand_buzz 的这个规模购买后可用，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/billing/","param":"scale","note":"This runs only for an account that has bought credits. Buy credits, then send the same request again: https://socialtoai.app/console/billing/"}` |

### `key_scope_denied` (HTTP 403, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这把 Key 没有开 read_data 这项权限，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/keys/","allowed":["read_data"],"note":"Its owner can turn the permission on in the key's settings; it holds from the next call."}` |

### `not_found` (HTTP 200 / 404, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 对象不存在、私密或已删除，本次没有扣费。 | `{"param":"id","note":"Check the id or link; content that is private, deleted or not there cannot be read. Sending the same lookup again will not help."}` |
| – | 没有这个结果，或者它不是这把 Key 发起的。本次没有扣费。 | `{"param":"handle","note":"A result is read with the key that started its call. What was run in the console is read in the console."}` |
| – | 没有这个热榜，或这一周没有热榜。 | `{"note":"GET /v1/boards lists the boards offered and the weeks each one keeps."}` |
| – | 这个词不在这个平台的指数词库里（不是热度为 0），数据来源照常计费，本次按价扣费。换个更常见、更短的词再查，或先用搜索看大家怎么说这件事。 | `{"param":"keyword","note":"Asking for the same word again gets the same answer and is charged again. Try a broader or more common word; a search on the same platform shows how people put it."}` |
| – | 没有这个定时，本次没有扣费。 | `{"param":"id","note":"GET /v1/schedules lists the schedules of the account."}` |
| – | 没有这个订阅地址：它可能已被换掉或关掉。 | `{"note":"The watch's owner finds its current address in the console's Tasks page, or with watch action=list."}` |
| – | 没有这个工具，本次没有扣费。 | `{"param":"tool","allowed":["brand_buzz","comment_insights","account_watch","find_creators","creator_card","batch_stats","viral_finder"],"note":"POST /v1/tools/{tool} takes one of these."}` |
| – | 没有这个路由，本次没有扣费。 | `{"allowed":["POST /v1/{search\|trending\|detail\|comments\|user_profile\|user_posts}","POST /v1/call/{op}","POST /v1/tools/{tool}","GET /v1/results/{handle}","POST /v1/find","GET /v1/capabilities","GET /v1/account","GET /openapi.json"],"example_call":{"method":"GET","path":"/v1/capabilities"},"note":"No such route. GET /v1/capabilities lists what can be called, with a call for each."}` |

### `idempotency_in_progress` (HTTP 409, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 同一个 Idempotency-Key 的调用还在进行。 | `{"note":"Ask again with the same Idempotency-Key shortly."}` |

### `handle_expired` (HTTP 410, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这个结果已过保存期，取不回了。本次没有扣费。 | `{"note":"Run the call again for a new result: that is a new call, charged as one."}` |

### `idempotency_conflict` (HTTP 422, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这个 Idempotency-Key 已用于另一组参数。 | `{"param":"Idempotency-Key","note":"Use a new key for a different request."}` |

### `daily_limit_reached` (HTTP 429, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| `key` | 这把 Key 今天的每日上限已到，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/","note":"The limit starts again at resets_at (UTC midnight); its owner can raise it or switch it off."}` |
| `account` | 账户今天的每日上限已到，本次没有扣费。 | `{"action_url":"https://socialtoai.app/console/","note":"The limit starts again at resets_at (UTC midnight); its owner can raise it or switch it off."}` |

### `free_failure_limit` (HTTP 429, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 失败的调用太多，暂时不能再调用，本次没有扣费。 | `{"note":"Correct the request as the fix of the earlier errors says, and send it again after retry_at."}` |

### `rate_limited` (HTTP 429, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| `key_qps` | 这把 Key 调用得太快，本次没有扣费。 | `{"note":"Wait for Retry-After seconds, then send the request again."}` |
| `workspace_concurrency` | 同时在跑的调用已到上限，本次没有扣费。 | `{"note":"Wait for Retry-After seconds, then send it again, and run fewer calls side by side: the account has a limit on calls running at once."}` |
| `address` | 这个网络地址的请求太多。 | `{"note":"Wait for Retry-After seconds, or send a key."}` |

### `internal_error` (HTTP 500, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| `run_abandoned` | 运行超时被中止，没有扣费，可以再运行一次。 | `{"action_url":"https://socialtoai.app/status/","note":"Start it again as a new run. If it stops again, ask for less in one run: fewer accounts or targets, or a smaller scale."}` |
| – | 我们这边出了错，本次没有扣费。 | `{"action_url":"https://socialtoai.app/status/","note":"Send the request again; under the same Idempotency-Key it is never charged twice."}` |

### `temporarily_unavailable` (HTTP 200 / 503, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这个账户今天不能再发起调用，本次没有扣费。 | `{"note":"Calls are accepted again at resets_at (UTC midnight)."}` |
| – | 这个调用暂时不可用，本次没有扣费。 | `{"action_url":"https://socialtoai.app/status/"}` |

### `invalid_target` (HTTP 200, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | url 指向的目标无效，本次没有扣费。 | `{"param":"url","note":"Check the link: pass the account's or the post's own address as the platform shows it in a browser. If it still fails, find the account or post with a search first (type: \"user\" for accounts where the platform has it) and pass the link or id it shows."}` |
| – | 这个平台的用户名只由英文字母、数字和少数符号（如 _ . -）组成；username 里给的像是显示名，不会有账号叫这个，查询没有发出，本次没有扣费。 | `{"param":"username","note":"Find the account first (search with type: \"user\" where the platform has it, or the profile link), then pass the username it shows."}` |

### `upstream_error` (HTTP 200, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这次没有从数据来源取到结果，本次没有扣费。 | `{"note":"Send it once more after 5 seconds. If the same request fails again, the content itself most likely cannot be had: change the input rather than retrying."}` |
| – | 这个品牌多半不在品牌库里：这个接口只回答库里的品牌（名字要和巨量算数收录的写法一致，目前能查到的多是母婴类）。本次没有扣费。 | `{"param":"brand","example_call":{"method":"POST","path":"/v1/search","body":{"platform":"douyin","query":"露营"}},"note":"Asking again will not help: the same brand gets the same answer. Try the name as the index spells it. Or read what people post about the brand with a search on douyin, as in example_call; or the heat of its name with op douyin.keyword_history (a word the index does not cover comes back empty and is charged)."}` |
| – | 这条帖子显示有 81 条评论，这次没有取到，没有扣费，可以稍后再试。 | `{"note":"The source answered with no comments for a post that has them. The same request at once gets the same answer: try again in a while."}` |
| – | 这个平台的指数里查不到这个账号的数据。最常见的原因是传了账号的号（username）而不是 uid：uid 在同一平台账号资料（user_profile）返回的 extra.uid 里。如果传的已经是 uid，就是这个账号粉丝太少、指数里没有它，重试也取不到。本次没有扣费。 | `{"param":"id","note":"Read extra.uid from user_profile on the same platform (by the account's link or id), then send it here as id."}` |
| – | 这个平台的搜索把“最热”排序和时间范围放在一起时常常取不到结果：去掉 published_within，或者不用 sort=popular 再搜。本次没有扣费。 | `{"param":"sort","note":"Sending the same search again will not help: change sort or published_within."}` |

### `timeout` (HTTP 200, 不扣费)

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 结果不确定，本次没有扣费；请勿自动重试。 | `{"note":"If the data is still needed, send a new request."}` |
