Errors

Every error response is a JSON body with an error field. The error value is sometimes a machine-readable slug (e.g. "no_credits", "limit_reached") and sometimes a human-readable sentence — see the table below for which is which. Status codes are consistent across all four platform endpoints.

{ "error": "Description or slug" }

Status codes

Code	Name	When it fires	`error` field
`400`	Bad Request	Invalid JSON body, missing `url`, or `url` doesn’t match the expected platform format	`Invalid JSON body` / `Missing "url" in request body` / `Invalid URL. Please provide a valid <Platform> video URL.`
`401`	Unauthorized	Missing, malformed, or revoked API key	`Invalid API key`
`403`	Forbidden	Account out of credits	`no_credits` (slug) — body also includes `credits: 0` and a human-readable `message`
`404`	Not Found	Upstream platform reported the video doesn’t exist, is private, or has no transcript available	`Video not found` / `Shoot the post does not have a video` / `No transcript available for this video` (varies — comes from upstream)
`429`	Rate Limited	120 req/min cap exceeded for this key	`Rate limit exceeded. Try again later.` — see rate limits
`500`	Internal Error	Unexpected worker error, or `SCRAPECREATORS_API_KEY` unset on the server side	`Internal server error` / `API key not configured`
`502`	Bad Gateway	Upstream platform API returned a non-2xx HTTP status	`Failed to fetch transcript` — body also includes a `details` string echoing the upstream payload

404 vs 502: a 502 means the upstream HTTP request itself failed (network error, upstream 5xx, etc.). A 404 means the upstream returned 200 but flagged the video as not retrievable (deleted, private, no captions). Treat both as “this video can’t be transcribed today” — but only 502 is worth retrying.

Retry guidance

Retry only on 429 and 502. Use exponential backoff with jitter, and cap retries at 3–5 attempts. Don’t retry on other 4xx codes — the request itself is wrong, retrying won’t fix it.

A common pattern:

import time, random, requests

def call_with_backoff(url, payload, headers, max_retries=4):
    for attempt in range(max_retries):
        r = requests.post(url, json=payload, headers=headers)

        if r.status_code < 400:
            return r

        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue

        if r.status_code == 502:
            time.sleep((2 ** attempt) + random.uniform(0, 1))
            continue

        # Non-retriable error (400, 401, 403, 404, 500)
        r.raise_for_status()

    r.raise_for_status()

Reporting issues

If you hit a status code that doesn’t match the table above, or you see persistent 5xx errors on a URL you believe should work, email hello@transcriptmagic.com with the URL and approximate timestamp — we’ll investigate.

Get started

MCP Server

n8n

Concepts

Status codes

Retry guidance

Reporting issues

​Status codes

​Retry guidance

​Reporting issues

Status codes

Retry guidance

Reporting issues