错误
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 | 免费账户能做的已经到头:可发起的调用用完了,批量在首次购买后才开放,或它已经有 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_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"} |
| – | 这个平台的 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_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."} |
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."} |
unauthorizedHTTP 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_balanceHTTP 402不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 余额不足,本次需要 10 积分,没有扣费。 | {"action_url":"https://socialtoai.app/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.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_deniedHTTP 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_foundHTTP 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_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.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_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 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_errorHTTP 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_unavailableHTTP 200 / 503不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 这个账户今天不能再发起调用,本次没有扣费。 | {"note":"Calls are accepted again at resets_at (UTC midnight)."} |
| – | 这个调用暂时不可用,本次没有扣费。 | {"action_url":"https://socialtoai.app/status/"} |
invalid_targetHTTP 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_errorHTTP 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."} |
timeoutHTTP 200不扣费
| reason | 返回的文字 | fix |
|---|---|---|
| – | 结果不确定,本次没有扣费;请勿自动重试。 | {"note":"If the data is still needed, send a new request."} |
最近更新: