Docs

Errors

Every error code, its HTTP status, whether a later retry can succeed, and what to do about it.

Errors return a non-2xx status and a JSON body with a machine-readable code, a human-readable message and the request_id to quote when contacting support:

404 response

{
  "error": {
    "code": "not_found",
    "message": "The item does not exist or was deleted.",
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f"
  }
}

code values are stable; message wording may change. See Credits for how failed requests are billed.

Error codes

Retry says whether sending the same request again later can get a different answer. What to do is the recommended reaction.

Code	HTTP	Retry	Meaning	What to do
`invalid_input`	400	No	The request parameters are missing or malformed, or the URL is not a supported link for this endpoint.	Fix the parameter named in the message; see the endpoint's accepted URL forms.
`invalid_cursor`	400	No	The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it.	Repeat the original request without cursor to start the list again.
`unauthorized`	401	No	The x-api-key header is missing, unknown or revoked.	Send a valid API key in the x-api-key header.
`insufficient_credits`	402	No	The account does not have enough credits for this request.	Buy a credit pack, then repeat the request.
`rate_limited`	429	Yes, later	The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request.	Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more.
`method_not_allowed`	405	No	The endpoint exists but does not accept this HTTP method.	Use the method in the allow header (GET for every data endpoint).
`not_found`	404	No	The item does not exist or was deleted.	Check the URL or ID; do not retry.
`private_or_unavailable`	403	No	The item exists but is private, age- or region-gated, or requires a login to view.	Only public items can be fetched; do not retry.
`no_transcript`	404	No	The media exists but has no transcript: no caption track and no speech to transcribe.	Do not retry; try another language with lang if the platform offers one.
`upstream_blocked`	503	Yes, later	The platform refused every attempt.	Retry later with backoff; failed requests are free.
`upstream_error`	502	Yes, later	The platform failed or returned something unexpected.	Retry with backoff; failed requests are free.
`overloaded`	503	Yes, later	Every SocialTap engine instance that could serve the request was at capacity; no upstream work was done. Capacity grows with traffic, so this is brief.	Retry after the number of seconds in the retry-after header; failed requests are free.
`internal`	500	Yes, later	Unexpected SocialTap error.	Retry with backoff; contact support with the request_id if it persists.

Retrying

Retry: yes. Retry with exponential backoff and a cap on attempts. For rate_limited, wait at least the number of seconds in the retry-after header first, then retry. It is not a plan limit but the per-account safety ceiling against runaway clients (see Rate limits).
Retry: no. The code describes your request or the item, and the same request gets the same answer on every attempt: fix the input, top up your balance, or treat the item as unavailable, as the table says.