# Fehler behandeln

> So liest du API-Fehler, erkennst fehlgeschlagene Transkriptionen und entscheidest, wann sich ein neuer Versuch lohnt.

Canonical: https://transcript1.com/de/docs/errors
Language: de
Last updated: 2026-10-19

Unterscheide zwischen einem abgelehnten Request und einer fehlgeschlagenen Transkription. Im ersten Fall nimmt die API den Aufruf nicht an. Im zweiten hat sie die Transkription angenommen, die Verarbeitung scheitert aber später. Dann steht `status` auf `failed`.

## So liest du eine Fehlerantwort

Wenn die API einen Request unter `/v1` ablehnt, bekommst du immer dieses Fehlerformat:

```json
{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}
```

Steuere deine Fehlerbehandlung über `code`. `message` kannst du deinen Nutzern anzeigen, solltest dich aber nicht auf den Wortlaut verlassen. Er kann sich ändern. Steht `retryable` auf `true`, kann derselbe Request zu einem späteren Zeitpunkt funktionieren.

Je nach Fehler kommen neben `retryable` weitere Felder hinzu:

| Feld | Fehlercode | Was darin steht |
|---|---|---|
| `action_url` | `insufficient_minutes` | Link zum Kauf eines Tarifs oder einer Minuten-Aufladung. |
| `minutes_needed`, `minutes_remaining` | `insufficient_minutes` | Benötigte Minuten und dein verfügbares Guthaben. Solange die benötigte Menge noch nicht feststeht, ist der erste Wert `null`. |
| `supported_platforms` | `unsupported_platform` | Liste der erlaubten Plattformen: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`. |
| `missing_chunks` | `upload_incomplete` | Indizes der noch fehlenden Chunks. |
| `max_bytes` | `media_too_large` | Deine maximal erlaubte Dateigröße in Bytes. |
| `params` | `invalid_request` | Bei ungültigen Body- oder Query-Feldern: ein Objekt mit dem jeweiligen Feldnamen und dem zugehörigen Problem. |

## Wenn die API den Request ablehnt

| HTTP-Status | `code` | Erneut versuchen? | Ursache und nächster Schritt |
|---|---|---|---|
| 400, 422 | `invalid_request` | Nein | Ein Parameter oder Body-Feld fehlt oder hat einen ungültigen Wert. Beispiele sind `diarize` mit `source: "captions"` oder `reuse_recent` mit `webhook_url`. Auch ungültiges JSON im Request-Body löst diesen Fehler aus. |
| 422 | `invalid_url` | Nein | Das Linkformat wird nicht unterstützt oder der Link passt nicht zu `platform`. Verwende YouTube, X, TikTok, Instagram, Facebook, Bluesky oder eine weitere Plattform aus [Quellen und Einstellungen](https://transcript1.com/de/docs/sources-and-options). |
| 422 | `unsupported_platform` | Nein | Der Wert von `platform` ist nicht erlaubt. |
| 422 | `unsupported_media` | Nein | Die Dateiendung des Uploads wird nicht unterstützt. |
| 401 | `unauthorized` | Nein | Zugangsdaten fehlen, sind ungültig, abgelaufen oder widerrufen. Auch ein ungültiges oder abgelaufenes Upload-Token führt zu diesem Fehler. |
| 403 | `insufficient_scope` | Nein | Dem OAuth-Token fehlt die Berechtigung `transcriptions:read` oder `transcriptions:write`. |
| 403 | `email_not_verified` | Nein | Deine E-Mail-Adresse ist noch nicht bestätigt. Hole das nach, bevor du eine Transkription startest. |
| 402 | `insufficient_minutes` | Nein | Du hast 0 nutzbare Minuten oder weniger, als die Transkription braucht. |
| 402 | `no_active_plan` | Nein | Für die Minuten-Aufladung fehlt ein aktiver bezahlter Tarif. Diesen Fehler liefert nur der Billing-Endpoint des Dashboards, nicht einer der Transkriptions-Endpoints. |
| 404 | `not_found` | Nein | Unter dieser ID gibt es keine Transkription, oder sie gehört zu einem anderen Team. |
| 409 | `upload_incomplete` | Nein | Lade die fehlenden Chunks hoch und rufe danach den Abschluss erneut auf. |
| 409 | `invalid_state` | Nein | Die Transkription wartet nicht auf einen Upload. Du kannst weder weitere Chunks senden noch den Upload abschließen. |
| 409 | `idempotency_conflict` | Nein | Derselbe `Idempotency-Key` wurde schon für andere Parameter verwendet. |
| 413 | `media_too_large` | Nein | Die Datei überschreitet dein Größenlimit. Die Grenzen stehen unter [Dateien hochladen](https://transcript1.com/de/docs/uploads). |
| 413 | `invalid_request` | Nein | Der JSON-Body ist größer als 1 MB. Bei zu großen Dateien heißt der Fehler stattdessen `media_too_large`. |
| 429 | `rate_limited` | Ja | Du hast zu viele Requests pro Minute gesendet. Warte so viele Sekunden, wie `Retry-After` vorgibt. |
| 429 | `too_many_active_jobs` | Ja | Es laufen zu viele Transkriptionen oder es sind zu viele Uploads offen. Warte die in `Retry-After` angegebene Zahl von Sekunden. |
| 500 | `internal_error` | Ja | Bei uns ist ein Fehler aufgetreten. Versuche es nach einer kurzen Pause erneut. |
| 503 | `service_unavailable` | Ja | transcript1 ist gerade nicht verfügbar. Versuche es nach einer kurzen Pause erneut. |

Bei Browser-Requests mit Login-Cookie statt Bearer-Zugangsdaten prüft die API zusätzlich die Herkunft. Kommt der Request von einer anderen Website, bekommst du `403 forbidden_origin`. Für API-Aufrufe mit `Authorization`-Header gilt diese Prüfung nicht.

Bei jedem `429` steht im Header `Retry-After`, wie viele Sekunden du warten musst. Die konkreten Grenzen findest du unter [Abrechnung und Limits](https://transcript1.com/de/docs/billing-and-limits).

## Wann du einen Request wiederholen solltest

- Wiederhole den Request nur, wenn `retryable` auf `true` steht: bei `rate_limited`, `too_many_active_jobs`, `internal_error` und `service_unavailable`. Warte die Zeit aus `Retry-After` ab, falls der Header vorhanden ist. Fehlt er, vergrößere die Pause zwischen den Versuchen.
- Verwende bei jedem neuen Versuch für `POST /v1/transcriptions` denselben `Idempotency-Key`-Header. Hat der erste Request doch funktioniert, verhinderst du damit eine doppelte Berechnung.
- Bei allen anderen Fehlercodes musst du zuerst den Request korrigieren.

## Wenn die Transkription später fehlschlägt

Auch nach der API-Antwort kann die Verarbeitung noch scheitern. Hat `status` den Wert `failed`, enthält das Transkriptionsobjekt `error: { "code", "message" }`. Prüfe `error` beim Polling oder lies es im [Webhook](https://transcript1.com/de/docs/webhooks) vom Typ `transcription.failed`.

| `error.code` | Ursache | Was du tun kannst |
|---|---|---|
| `media_unavailable` | Das Video fehlt oder ist nicht mehr abrufbar. | Nicht unverändert wiederholen. Prüfe den Link. |
| `media_private` | Das Video ist als privat eingestellt. | Nicht wiederholen. Verwende einen öffentlichen Post; bei YouTube geht auch ein nicht gelistetes Video. |
| `login_required` | Ohne Anmeldung gibt die Plattform das Video nicht frei. | Nicht wiederholen. Der Fehler ist dauerhaft; transcript1 versucht es nicht erneut. |
| `no_audio` | Im Video fehlt die Tonspur. | Nicht wiederholen. Der Fehler ist dauerhaft; transcript1 versucht es nicht erneut. |
| `age_restricted` | Für das Video gilt eine Altersbeschränkung. | Nicht wiederholen. Lade stattdessen die Datei hoch. |
| `live_stream` | Der Stream läuft noch oder hat noch nicht begonnen. | Versuche es nach Ende des Streams erneut. |
| `no_captions` | Mit `source` auf `captions` findet transcript1 keine nutzbare Untertitelspur. | Wähle stattdessen `source: "auto"` oder `"stt"`. |
| `media_too_long` | Die Aufnahme überschreitet das Speech-to-Text-Limit von 5 Stunden. | Nicht unverändert wiederholen. Teile die Aufnahme auf. |
| `unsupported_media` | Die Datei lässt sich nicht lesen oder enthält keine Audiospur. | Nicht wiederholen. Sende eine Datei in einem unterstützten Format. |
| `no_speech` | transcript1 hat keine gesprochenen Worte erkannt. | Nicht wiederholen. |
| `unsupported_language` | Die Sprache der Aufnahme wird nicht unterstützt. | Nicht unverändert wiederholen. Setze `language` auf einen unterstützten Sprachcode oder `"auto"`. |
| `insufficient_minutes` | Vor der Abrechnung der Transkription waren deine Minuten aufgebraucht. | Lade Minuten auf und versuche es danach erneut. |
| `fetch_failed` | transcript1 konnte die Aufnahme auch nach mehreren Versuchen nicht abrufen. | Versuche es später erneut. |
| `transcription_failed` | Speech-to-Text ist trotz mehrerer Versuche gescheitert. | Versuche es später erneut. |

Wenn eine Transkription fehlschlägt oder abgebrochen wird, zahlst du nichts. Bereits abgezogene Minuten schreiben wir dir in diesen Fällen wieder gut.