错误
SocialToAI 一共有 19 个错误代码，全都不扣费。执行前被拒绝的请求返回 HTTP 错误状态码；平台那边的失败仍是 HTTP 200，错误写在返回体里。每个错误都带 request_id 和 fix，后者说明怎么改正。
全部代码
| 代码 | 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_paramsHTTP 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_supportedHTTP 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."} |
unauthorizedHTTP 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_balanceHTTP 402不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 余额不足，本次需要 10 积分，没有扣费。 | {"action_url":"https://socialtoai.com/console/billing/","note":"Buy credits, then send the same request again."} |
max_cost_exceededHTTP 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_limitHTTP 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_deniedHTTP 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_foundHTTP 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_progressHTTP 409不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 同一个 Idempotency-Key 的调用还在进行。 | {"note":"Ask again with the same Idempotency-Key shortly."} |
handle_expiredHTTP 410不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 这个结果已过保存期，取不回了。本次没有扣费。 | {"note":"Run the call again for a new result: that is a new call, charged as one."} |
idempotency_conflictHTTP 422不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 这个 Idempotency-Key 已用于另一组参数。 | {"param":"Idempotency-Key","note":"Use a new key for a different request."} |
daily_limit_reachedHTTP 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_limitHTTP 429不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 失败的调用太多，暂时不能再调用，本次没有扣费。 | {"note":"Correct the request as the fix of the earlier errors says, and send it again after retry_at."} |
rate_limitedHTTP 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_errorHTTP 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_unavailableHTTP 200 / 503不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 这个账户今天不能再发起调用，本次没有扣费。 | {"note":"Calls are accepted again at resets_at (UTC midnight)."} |
| – | 这个调用暂时不可用，本次没有扣费。 | {"action_url":"https://socialtoai.com/status/"} |
invalid_targetHTTP 200不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | url 指向的目标无效，本次没有扣费。 | {"param":"url"} |
upstream_errorHTTP 200不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 数据来源出错，本次没有扣费。 | {"note":"Send the request again later."} |
timeoutHTTP 200不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 结果不确定，本次没有扣费；请勿自动重试。 | {"note":"If the data is still needed, send a new request."} |
最近更新：