> ## 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 four 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.`                  |
| `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](/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.