---
title: "Errors · Docs · SocialToAI"
canonical: https://socialtoai.app/docs/api/errors/
updated: 2026-11-20
---

# Errors

SocialToAI has 19 error codes, and none of them is charged. A request refused before it runs answers with an HTTP error status; a failure on the platform's side comes back under HTTP 200 with the error inside the answer. Every error carries a request_id and a fix that says how to correct the call.

- Page: https://socialtoai.app/docs/api/errors/
- Last updated: 2026-11-20

## All codes

| Code | HTTP | What happened, and what to do | Retry | Charged |
| --- | --- | --- | --- | --- |
| `invalid_params` | 400 | A parameter is missing or wrong. Nothing ran. Correct it using `fix` in the response. | No | No |
| `not_supported` | 400 | The platform does not offer that action. `fix.allowed` lists the platforms that do. | No | No |
| `unauthorized` | 401 | The key is missing, wrong, expired or suspended. Send a current key in a header. `reason` says which case it is. | No | No |
| `insufficient_balance` | 402 | Not enough credits for this call. Nothing ran. Buy credits, then send it again. | No | No |
| `max_cost_exceeded` | 402 | The call costs more than your `max_cost_credits`. Nothing ran. `quote_credits` is what it would cost. | No | No |
| `plan_limit` | 403 | A free account has reached what it can do: its calls are used up, batches open after the first purchase, or it keeps its one schedule (watch) already. Nothing ran. Buy credits to continue. | No | No |
| `key_scope_denied` | 403 | This key is not permitted to do that. Turn the permission on in the key's settings. | No | No |
| `not_found` | 200 / 404 | The post or account does not exist, is private or was deleted; `why` says which when the platform tells, and `platform_says` gives its own words. Where the platform's source charges for the lookup, the call is charged its price and the error says `charged: true`. Nothing to retry. An unknown path also answers with this code. | No | At price, where the source charges |
| `idempotency_in_progress` | 409 | The call under this `Idempotency-Key` is still running. Ask again with the same key after `Retry-After`. | Yes | No |
| `handle_expired` | 410 | The stored result is no longer kept. Send the call again. | No | No |
| `idempotency_conflict` | 422 | This `Idempotency-Key` was used with other parameters. Use a new key for a different request. | No | No |
| `daily_limit_reached` | 429 | A daily limit is reached. Nothing ran. The limit is on the key or the account and starts again at `resets_at`. | No | No |
| `free_failure_limit` | 429 | Too many failed calls in a short time. Wait until `retry_at`, then send it again. | Yes | No |
| `rate_limited` | 429 | Too many calls per second for this key, or too many running at once. Wait for `Retry-After`, then send it again. | Yes | No |
| `internal_error` | 500 | The run was stopped because it ran out of time. Nothing was charged; it can be run again. | Yes | No |
| `temporarily_unavailable` | 200 / 503 | This call is paused for now. The status page says why. Try again later. | Yes | No |
| `invalid_target` | 200 | The link or ID does not point at a valid target. Check the value named in `fix.param`. | No | At price, where the source charges |
| `upstream_error` | 200 | No result came from the platform this time; it was already tried up to three times on our side. When `retryable` is true, send it once more after `retry_after_seconds`. If the same request fails again, the content itself most likely cannot be had: change the input. | Depends | No |
| `timeout` | 200 | No result in time, and we cannot tell whether it ran. We cover the cost. We never retry on our own (`X-Should-Retry: false`). Send a new request if you still need it. | No | No |

## Each code, case by case

The messages below are what the API answers with, and `fix` is an example of what comes with them.

### `invalid_params` (HTTP 400, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | The request body must be a JSON object. | `{"param":"platform"}` |
| – | query must be text of 1 to 500 characters. | `{"param":"query"}` |
| – | limit must be a whole number from 1 to 50. | `{"param":"limit"}` |
| – | platform is required. | `{"param":"platform","allowed":["tiktok","instagram","x"]}` |
| – | lang is not a parameter of this call. | `{"param":"lang","allowed":["query","sort"]}` |
| – | query must be a non-empty string or a whole number. | `{"param":"query"}` |
| – | On this platform sort is one of relevance, latest. Nothing was charged. | `{"param":"sort","allowed":["relevance","latest"]}` |
| – | query is required. | `{"param":"query"}` |
| – | since must be an ISO 8601 date (2026-10-01) or time (2026-10-01T08:00:00Z). Nothing was charged. | `{"param":"since"}` |
| – | since must not be later than now, nor later than until. Nothing was charged. | `{"param":"since"}` |
| – | Give exactly one of id, url. | `{"param":"id","allowed":["id","url"]}` |
| – | Only one of id, url may be a list. | `{"param":"url","note":"Each value of the list is fetched and charged as a call of its own."}` |
| – | One request takes at most 20 platforms or targets. | `{"param":"platform","note":"Send at most 20 at a time."}` |
| – | With this limit the request would take more than 40 pages in all. Nothing was charged. | `{"param":"limit","note":"Ask for fewer items or fewer platforms, or go on from page.cursor in a next request."}` |
| – | This call does not offer comments as an include. Nothing was charged. | `{"param":"include","allowed":[]}` |
| – | Idempotency-Key must be 1 to 255 visible ASCII characters. | `{"param":"Idempotency-Key"}` |
| – | The cursor is not valid for this request or has expired. Nothing was charged. | `{"param":"cursor","note":"Send the request again without cursor to start from the first page."}` |
| – | max_cost_credits must be a whole number, 0 or more. | `{"param":"max_cost_credits"}` |
| – | format is one of json, csv and ndjson. | `{"param":"format","allowed":["json","csv","ndjson"]}` |
| – | The data source does not take this value of query. Nothing was charged. | `{"param":"query","note":"What the source says is wrong: query must be at most 100 characters. Change query and send the request again."}` |
| – | window is not a value this tool takes. Nothing was charged. | `{"param":"window","allowed":["7d","30d"]}` |
| – | platforms takes at most 5. Nothing was charged. | `{"param":"platforms","note":"Send at most 5."}` |
| – | targets holds a link whose platform cannot be told. Nothing was charged. | `{"param":"targets","note":"Give the whole link to the post or to the account page, as the platform shows it."}` |
| – | targets holds a link that does not say which post it is (a short link, or no post's page). Nothing was charged. | `{"param":"targets","note":"Give the whole link to the post, as the platform shows it in the address bar."}` |
| – | accounts holds a link that does not say which account it is (a short link, or no account's page). Nothing was charged. | `{"param":"accounts","note":"Give the whole link to the account's page, as the platform shows it in the address bar."}` |
| – | This preview has expired. Nothing was charged. | `{"param":"token","note":"Call watch with action=preview again, show the user the new preview, and confirm with its token."}` |
| – | An account has at most 20 schedules. Nothing was charged. | `{"note":"Delete a schedule that is no longer needed, then make this one."}` |
| – | push_url is not the incoming-webhook address of a Feishu (Lark), WeCom or Slack group bot. Nothing was charged. | `{"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."}` |
| – | The group bot did not take the test message. Nothing was saved or charged. | `{"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."}` |
| – | A b23.tv short link has to be opened to tell which video it is, and short links are not opened here: open it in a browser and pass the bilibili.com/video/BV… address it lands on, or the BV id. Nothing was charged. | `{"param":"url","note":"Pass id: \"BV1…\", or url: \"https://www.bilibili.com/video/BV1…\"."}` |
| – | Invalid request: range must be one of: today, 14d. Nothing was charged. | `{"param":"range","note":"Correct the query parameter named here and send the request again."}` |
| – | The request body is not valid JSON. | `{"note":"Send one JSON object with Content-Type: application/json."}` |
| – | The request body is too large. Nothing was charged. | `{"note":"Send fewer targets in one request."}` |

### `not_supported` (HTTP 400, not charged)

| reason | Message | fix |
| --- | --- | --- |
| `no_such_capability` | This platform has no search. | `{"param":"platform","allowed":["tiktok","instagram","x"]}` |
| `not_available_yet` | search is not available on this platform yet. Nothing was charged. | `{"param":"platform","allowed":["tiktok","instagram","x"]}` |
| `no_such_capability` | There is no tiktok.name in the catalog. Nothing was charged. | `{"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 is not available yet. Nothing was charged. | `{"param":"op","allowed":[],"note":"GET /v1/capabilities lists what can be called now."}` |
| `no_such_capability` | search on this platform has no such type. Nothing was charged. | `{"param":"type","note":"Leave type out, or give another value."}` |
| `not_available_yet` | search is not available on this platform with this sort yet. Nothing was charged. | `{"param":"sort","note":"Leave sort out, or give another value."}` |
| – | Pushing to a group chat is not available here. Nothing was charged. | `{"param":"push_url","note":"Use email or a webhook instead."}` |
| `not_available_yet` | brand_buzz cannot run on tiktok now. Nothing was charged. | `{"allowed":["tiktok","instagram","x"],"note":"Use one of the platforms it runs on now."}` |
| `not_available_yet` | brand_buzz is not run at this scale for this request. Nothing was charged. | `{"param":"scale","allowed":["small"],"note":"Use a smaller scale, or fewer platforms or targets."}` |
| `not_available_yet` | This run of brand_buzz is not available yet. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| `missing` | The API key is missing, mistyped or does not exist. Nothing was charged. | `{"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` | The API key is missing, mistyped or does not exist. Nothing was charged. | `{"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` | This address does not take a key in the URL. The key is now exposed: revoke it, create a new one and send it in a header. Nothing was charged. | `{"action_url":"https://socialtoai.app/console/","note":"Send the key as Authorization: Bearer <key> or X-API-Key: <key>."}` |
| `suspended` | This account is suspended. Nothing was charged. | `{"note":"Write to support@socialtoai.app."}` |
| `expired` | This key has expired. Nothing was charged. | `{"action_url":"https://socialtoai.app/console/","note":"Its owner can set a later expiry, or create a new key."}` |
| – | A valid session is required. | `{"action_url":"https://socialtoai.app/sign-in/","note":"Sign in again."}` |
| `revoked` | This key was revoked. Nothing was charged. | `{"action_url":"https://socialtoai.app/console/","note":"Create a new key."}` |
| `suspended` | This key was paused by the support team. Nothing was charged. | `{"note":"Write to support@socialtoai.app."}` |

### `insufficient_balance` (HTTP 402, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | The balance is too low: this call needs 10 credits. Nothing was charged. | `{"action_url":"https://socialtoai.app/console/billing/","note":"Buy credits, then send the same request again."}` |

### `max_cost_exceeded` (HTTP 402, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This call needs 10 credits, more than max_cost_credits allows. Nothing was charged. | `{"param":"max_cost_credits","note":"Send max_cost_credits of at least 10, or leave it out."}` |

### `plan_limit` (HTTP 403, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This free account has used up the calls it can make. Nothing was charged. | `{"action_url":"https://socialtoai.app/console/billing/","note":"Buy credits to keep calling."}` |
| – | A free account keeps 1 schedule (watch). Nothing was charged. | `{"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 at this scale is available once credits have been bought. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This key does not have the read_data permission. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | The object does not exist, is private or was deleted. Nothing was charged. | `{"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."}` |
| – | There is no such result, or this key did not start it. Nothing was charged. | `{"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."}` |
| – | There is no such board, or no board of this week. | `{"note":"GET /v1/boards lists the boards offered and the weeks each one keeps."}` |
| – | This keyword is not in the platform's index (it is not a zero). The data source charges for the lookup all the same, so this call was charged at its price. Try a more common, shorter word, or search the platform first for how people put it. | `{"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."}` |
| – | There is no such schedule. Nothing was charged. | `{"param":"id","note":"GET /v1/schedules lists the schedules of the account."}` |
| – | There is no such feed: its address may have been changed or switched off. | `{"note":"The watch's owner finds its current address in the console's Tasks page, or with watch action=list."}` |
| – | There is no such tool. Nothing was charged. | `{"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."}` |
| – | There is no such route. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | The call under this Idempotency-Key is still running. | `{"note":"Ask again with the same Idempotency-Key shortly."}` |

### `handle_expired` (HTTP 410, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This result is past the time it is kept and cannot be read. Nothing was charged. | `{"note":"Run the call again for a new result: that is a new call, charged as one."}` |

### `idempotency_conflict` (HTTP 422, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This Idempotency-Key was used with other parameters. | `{"param":"Idempotency-Key","note":"Use a new key for a different request."}` |

### `daily_limit_reached` (HTTP 429, not charged)

| reason | Message | fix |
| --- | --- | --- |
| `key` | This key has reached its daily limit. Nothing was charged. | `{"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` | The account has reached its daily limit. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | Too many failed calls: new calls are refused until retry_at. Nothing was charged. | `{"note":"Correct the request as the fix of the earlier errors says, and send it again after retry_at."}` |

### `rate_limited` (HTTP 429, not charged)

| reason | Message | fix |
| --- | --- | --- |
| `key_qps` | This key is calling too fast. Nothing was charged. | `{"note":"Wait for Retry-After seconds, then send the request again."}` |
| `workspace_concurrency` | Too many calls are running at once. Nothing was charged. | `{"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` | Too many requests from this network address. | `{"note":"Wait for Retry-After seconds, or send a key."}` |

### `internal_error` (HTTP 500, not charged)

| reason | Message | fix |
| --- | --- | --- |
| `run_abandoned` | The run was stopped because it ran out of time. Nothing was charged; it can be run again. | `{"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."}` |
| – | Something failed on our side. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This account cannot start more calls today. Nothing was charged. | `{"note":"Calls are accepted again at resets_at (UTC midnight)."}` |
| – | This call is temporarily unavailable. Nothing was charged. | `{"action_url":"https://socialtoai.app/status/"}` |

### `invalid_target` (HTTP 200, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | url does not point at a valid target. Nothing was charged. | `{"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."}` |
| – | Usernames on this platform are Latin letters, digits and a few marks (such as _ . -) only: the username given reads as a display name, which no account has. Nothing was sent and nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | No result came from the data source this time. Nothing was charged. | `{"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."}` |
| – | This brand is most likely not in the brand index: this call only answers for brands the index lists (spelled as 巨量算数 lists them; so far mostly mother-and-baby brands). Nothing was charged. | `{"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)."}` |
| – | This post shows 81 comments, and none came back this time. Nothing was charged; try again later. | `{"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."}` |
| – | This platform's index has nothing on this account. Most often the account's handle (username) was given where its uid is wanted: the uid is extra.uid in what user_profile returns for the same platform. If it is the uid, the account has too few followers to be in the index, and asking again will not help. Nothing was charged. | `{"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."}` |
| – | This platform's search often gives nothing for sort=popular together with a time window: leave out published_within, or sort otherwise, and search again. Nothing was charged. | `{"param":"sort","note":"Sending the same search again will not help: change sort or published_within."}` |

### `timeout` (HTTP 200, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | The result is not known. Nothing was charged; do not retry automatically. | `{"note":"If the data is still needed, send a new request."}` |
