> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transcriptmagic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes you might see, and what they mean.

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.

```json theme={null}
{ "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` 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) |
| `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](/concepts/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 |

<Note>
  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.
</Note>

## Retry guidance

<Tip>
  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.
</Tip>

A common pattern:

```python theme={null}
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](mailto:hello@transcriptmagic.com) with the URL and approximate timestamp — we'll investigate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.