# 错误

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

- 页面：https://socialtoai.com/zh/docs/api/errors/
- 最近更新：2026-10-17

## 全部代码

| 代码 | 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 | 免费账户能做的已经到头：可发起的调用用完了，或这项功能（批量、定时）在首次购买后才开放。 没有执行。购买积分后继续。 | 不用 | 不扣 |
| `key_scope_denied` | 403 | 这把 Key 没有这项权限。 在这把 Key 的设置里打开对应权限。 | 不用 | 不扣 |
| `not_found` | 200 / 404 | 内容或账号不存在、是私密的，或已删除。 不用重试。路径写错时也返回这个代码。 | 不用 | 不扣 |
| `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` 说明再试一次有没有用。 | 视情况 | 不扣 |
| `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"}` |
| – | 缺少 query。 | `{"param":"query"}` |
| – | 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."}` |
| – | 这个调用不提供 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"]}` |
| – | 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."}` |
| – | 每个工作区最多 20 个定时，本次没有扣费。 | `{"note":"Delete a schedule that is no longer needed, then make this one."}` |
| – | 查询参数 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."}` |
| `not_available_yet` | 这个平台的 search 暂未提供 sort 的这个取值，本次没有扣费。 | `{"param":"sort","note":"Leave sort out, or give another value."}` |
| `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.com/console/","note":"Send a current key as Authorization: Bearer <key> or X-API-Key: <key>. Signing up gives a key and free credits; GET /v1/capabilities and POST /v1/find need none."}` |
| `invalid` | Key 缺失、粘贴不完整或不存在，本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/","note":"Send a current key as Authorization: Bearer <key> or X-API-Key: <key>. Signing up gives a key and free credits; GET /v1/capabilities and POST /v1/find need none."}` |
| `key_in_query` | 这个地址不收网址里的 Key；这把 Key 已经暴露，请撤销并新建一把，放在请求头里。本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/","note":"Send the key as Authorization: Bearer <key> or X-API-Key: <key>."}` |
| `suspended` | 这个账户已被暂停，本次没有扣费。 | `{"note":"Write to support@socialtoai.com."}` |
| `expired` | 这把 Key 已到期，本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/","note":"Its owner can set a later expiry, or create a new key."}` |
| – | 需要有效的登录会话。 | `{"action_url":"https://socialtoai.com/sign-in/","note":"Sign in again."}` |
| `revoked` | 这把 Key 已被撤销，本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/","note":"Create a new key."}` |
| `suspended` | 这把 Key 已被支持团队暂停，本次没有扣费。 | `{"note":"Write to support@socialtoai.com."}` |

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

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 余额不足，本次需要 10 积分，没有扣费。 | `{"action_url":"https://socialtoai.com/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.com/console/billing/","note":"Buy credits to keep calling."}` |
| – | 定时购买积分后可用，本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/billing/","note":"Buy credits; the schedule can then be made as it is."}` |
| – | brand_buzz 的这个规模购买后可用，本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/billing/","param":"scale","note":"Buy credits, or use a smaller scale: confirm: false answers which scales a free account may run."}` |

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

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 这把 Key 没有开 read_data 这项权限，本次没有扣费。 | `{"action_url":"https://socialtoai.com/console/","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; an object that is private or was deleted cannot be read."}` |
| – | 没有这个结果，或者它不是这把 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."}` |
| – | 没有这个定时，本次没有扣费。 | `{"param":"id","note":"GET /v1/schedules lists the schedules of the workspace."}` |
| – | 没有这个工具，本次没有扣费。 | `{"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.com/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.com/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 the request again."}` |
| `address` | 这个网络地址的请求太多。 | `{"note":"Wait for Retry-After seconds, or send a key."}` |

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

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 我们这边出了错，本次没有扣费。 | `{"action_url":"https://socialtoai.com/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.com/status/"}` |

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

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | url 指向的目标无效，本次没有扣费。 | `{"param":"url"}` |

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

| reason | 返回的文字 | fix |
| --- | --- | --- |
| – | 数据来源出错，本次没有扣费。 | `{"note":"Send the request again later."}` |

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

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