# 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.com/docs/api/errors/
- Last updated: 2026-10-17

## 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, or the feature (batches, schedules) opens after the first purchase. 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. Nothing to retry. An unknown path also answers with this code. | No | No |
| `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 | Something failed on our side. Nothing was charged. | 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 | No |
| `upstream_error` | 200 | The platform failed or returned an error. `retryable` says whether trying again can help. | 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"}` |
| – | query is required. | `{"param":"query"}` |
| – | 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."}` |
| – | 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"]}` |
| – | 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."}` |
| – | A workspace has at most 20 schedules. Nothing was charged. | `{"note":"Delete a schedule that is no longer needed, then make this one."}` |
| – | 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."}` |
| `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."}` |
| `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.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` | The API key is missing, mistyped or does not exist. Nothing was charged. | `{"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` | 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.com/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.com."}` |
| `expired` | This key has expired. Nothing was charged. | `{"action_url":"https://socialtoai.com/console/","note":"Its owner can set a later expiry, or create a new key."}` |
| – | A valid session is required. | `{"action_url":"https://socialtoai.com/sign-in/","note":"Sign in again."}` |
| `revoked` | This key was revoked. Nothing was charged. | `{"action_url":"https://socialtoai.com/console/","note":"Create a new key."}` |
| `suspended` | This key was paused by the support team. Nothing was charged. | `{"note":"Write to support@socialtoai.com."}` |

### `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.com/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.com/console/billing/","note":"Buy credits to keep calling."}` |
| – | Schedules are available once credits have been bought. Nothing was charged. | `{"action_url":"https://socialtoai.com/console/billing/","note":"Buy credits; the schedule can then be made as it is."}` |
| – | brand_buzz at this scale is available once credits have been bought. Nothing was charged. | `{"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, not charged)

| reason | Message | fix |
| --- | --- | --- |
| – | This key does not have the read_data permission. Nothing was charged. | `{"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, 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; an object that is private or was deleted cannot be read."}` |
| – | 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 schedule. Nothing was charged. | `{"param":"id","note":"GET /v1/schedules lists the schedules of the workspace."}` |
| – | 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.com/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.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, 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 the request again."}` |
| `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 |
| --- | --- | --- |
| – | Something failed on our side. Nothing was charged. | `{"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, 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.com/status/"}` |

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

| reason | Message | fix |
| --- | --- | --- |
| – | url does not point at a valid target. Nothing was charged. | `{"param":"url"}` |

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

| reason | Message | fix |
| --- | --- | --- |
| – | The data source failed. Nothing was charged. | `{"note":"Send the request again later."}` |

### `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."}` |