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 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.` (Twitch and Kick say `clip URL` — VOD, live-stream, and channel URLs are rejected)
`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`, a human-readable `message` and `upgradeUrl`, the page where this account can add credits (paid plans) or pick a plan (free plan). See running out
`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)
`422`	Unprocessable	The video has no captions and is longer than the 2-minute cap for AI transcription (mostly long Kick clips)	`This video has no captions and is longer than the 2-minute limit for AI transcription.` — body also includes `code: "too_long"`. Not retryable
`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.

Checkout errors

These come from buying credit packs on transcriptmagic.com, not from API calls. You’ll only see them if you build your own checkout flow on top of a signed-in session.

Code	`error`	When	Body
`403`	`plan_required`	A free account tried to buy a credit pack. Packs are for paid plans.	`message` (“Credit packs are for paying customers. Pick a plan to get started.”) and `upgradeUrl` (`https://transcriptmagic.com/credits/`)
`409`	`pack_changed`	The pack’s price changed since the page loaded.	`message` asking to refresh the page

An API key never gets plan_required: every plan, free included, can call the API.

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

Checkout errors

Retry guidance

Reporting issues

​Status codes

​Checkout errors

​Retry guidance

​Reporting issues

Status codes

Checkout errors

Retry guidance

Reporting issues