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.
All codes
| Code | HTTP | What happened, and what to do | Charged |
|---|---|---|---|
invalid_params | 400 | A parameter is missing or wrong.Nothing ran. Correct it using fix in the response.Retry: No | No |
not_supported | 400 | The platform does not offer that action.fix.allowed lists the platforms that do.Retry: 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.Retry: No | No |
insufficient_balance | 402 | Not enough credits for this call.Nothing ran. Buy credits, then send it again.Retry: No | No |
max_cost_exceeded | 402 | The call costs more than your max_cost_credits.Nothing ran. quote_credits is what it would cost.Retry: 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.Retry: No | No |
key_scope_denied | 403 | This key is not permitted to do that.Turn the permission on in the key's settings.Retry: 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.Retry: No | No |
idempotency_in_progress | 409 | The call under this Idempotency-Key is still running.Ask again with the same key after Retry-After.Retry: Yes | No |
handle_expired | 410 | The stored result is no longer kept.Send the call again.Retry: No | No |
idempotency_conflict | 422 | This Idempotency-Key was used with other parameters.Use a new key for a different request.Retry: 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.Retry: No | No |
free_failure_limit | 429 | Too many failed calls in a short time.Wait until retry_at, then send it again.Retry: 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.Retry: Yes | No |
internal_error | 500 | Something failed on our side. Nothing was charged.Retry: Yes | No |
temporarily_unavailable | 200 / 503 | This call is paused for now.The status page says why. Try again later.Retry: Yes | No |
invalid_target | 200 | The link or ID does not point at a valid target.Check the value named in fix.param.Retry: No | No |
upstream_error | 200 | The platform failed or returned an error.retryable says whether trying again can help.Retry: 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.Retry: 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_paramsHTTP 400not 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_supportedHTTP 400not 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."} |
unauthorizedHTTP 401not 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_balanceHTTP 402not 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_exceededHTTP 402not 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_limitHTTP 403not 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_deniedHTTP 403not 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_foundHTTP 200 / 404not 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_progressHTTP 409not charged
| reason | Message | fix |
|---|---|---|
| – | The call under this Idempotency-Key is still running. | {"note":"Ask again with the same Idempotency-Key shortly."} |
handle_expiredHTTP 410not 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_conflictHTTP 422not 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_reachedHTTP 429not 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_limitHTTP 429not 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_limitedHTTP 429not 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_errorHTTP 500not 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_unavailableHTTP 200 / 503not 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_targetHTTP 200not charged
| reason | Message | fix |
|---|---|---|
| – | url does not point at a valid target. Nothing was charged. | {"param":"url"} |
upstream_errorHTTP 200not charged
| reason | Message | fix |
|---|---|---|
| – | The data source failed. Nothing was charged. | {"note":"Send the request again later."} |
timeoutHTTP 200not 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."} |
Last updated: