# Obsługa błędów

> Sprawdź format odpowiedzi z błędem, wszystkie kody i zasady ponawiania requestów.

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

API może odrzucić request od razu albo przyjąć transkrypcję, która później się nie uda. To dwa różne przypadki. W drugim z nich pole `status` transkrypcji ma wartość `failed`.

## Jak wygląda odpowiedź z błędem

Endpointy `/v1` zwracają błędy requestów w takim formacie:

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

Logikę obsługi błędów oprzyj na `code`. Treść `message` pokazuj użytkownikowi, ale nie uzależniaj od niej działania aplikacji, bo może się zmienić. Jeśli `retryable` ma wartość `true`, ten sam request ma szansę udać się później.

Zależnie od błędu obok `retryable` mogą pojawić się dodatkowe pola:

| Pole | Kiedy je dostaniesz | Co zawiera |
|---|---|---|
| `action_url` | `insufficient_minutes` | Link do zakupu planu lub doładowania. |
| `minutes_needed`, `minutes_remaining` | `insufficient_minutes` | Liczbę minut potrzebnych do transkrypcji (`null`, jeśli jeszcze jej nie znamy) oraz dostępną pulę minut. |
| `supported_platforms` | `unsupported_platform` | Listę obsługiwanych platform: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`. |
| `missing_chunks` | `upload_incomplete` | Indeksy części pliku, których brakuje na serwerze. |
| `max_bytes` | `media_too_large` | Twój limit rozmiaru pliku w bajtach. |
| `params` | `invalid_request` | Przy błędach walidacji body i query: obiekt, którego klucze wskazują pola, a wartości opisują, co trzeba poprawić. |

## Gdy API odrzuci request

| Kod HTTP | `code` | Ponowić bez zmian? | Co sprawdzić |
|---|---|---|---|
| 400, 422 | `invalid_request` | Nie | Brakuje pola lub parametru, ma on błędną wartość albo body nie jest poprawnym JSON-em. Niedozwolone połączenia opcji to m.in. `diarize` z `source: "captions"` i `reuse_recent` z `webhook_url`. |
| 422 | `invalid_url` | Nie | Link musi prowadzić do nagrania z YouTube, X, TikToka, Instagrama, Facebooka, Bluesky lub innej platformy z [listy obsługiwanych linków](https://transcript1.com/pl/docs/sources-and-options). Sprawdź też, czy `platform` zgadza się z linkiem. |
| 422 | `unsupported_platform` | Nie | Wartość `platform` nie znajduje się na liście obsługiwanych platform. |
| 422 | `unsupported_media` | Nie | Rozszerzenie wysłanego pliku nie jest obsługiwane. |
| 401 | `unauthorized` | Nie | Brakuje danych uwierzytelniających albo są one błędne, wygasły lub je unieważniono. Ten kod oznacza też błędny lub wygasły token uploadu. |
| 403 | `insufficient_scope` | Nie | Tokenowi OAuth brakuje uprawnienia `transcriptions:read` lub `transcriptions:write`. |
| 403 | `email_not_verified` | Nie | Najpierw potwierdź e-mail, potem zleć transkrypcję. |
| 402 | `insufficient_minutes` | Nie | Masz 0 minut lub za mało na to nagranie. |
| 402 | `no_active_plan` | Nie | Doładowanie wymaga aktywnego płatnego planu. Ten błąd zwraca endpoint rozliczeń w panelu, nie endpointy transkrypcji. |
| 404 | `not_found` | Nie | Nie ma takiej transkrypcji lub należy ona do innego zespołu. |
| 409 | `upload_incomplete` | Nie | Doślij brakujące części pliku i jeszcze raz zakończ upload. |
| 409 | `invalid_state` | Nie | Transkrypcja nie czeka na upload. Nie możesz już dosyłać części ani kończyć uploadu. |
| 409 | `idempotency_conflict` | Nie | Pod tym `Idempotency-Key` wysłano już request z innymi parametrami. |
| 413 | `media_too_large` | Nie | Przekroczono limit rozmiaru pliku. Sprawdź [zasady wysyłania plików](https://transcript1.com/pl/docs/uploads). |
| 413 | `invalid_request` | Nie | JSON w body przekracza 1 MB. Dla zbyt dużych plików kodem błędu jest `media_too_large`. |
| 429 | `rate_limited` | Tak | Przekraczasz liczbę requestów na minutę. Odczekaj tyle sekund, ile wskazuje `Retry-After`. |
| 429 | `too_many_active_jobs` | Tak | Masz za dużo trwających transkrypcji lub otwartych uploadów. Odczekaj tyle sekund, ile wskazuje `Retry-After`. |
| 500 | `internal_error` | Tak | Błąd po naszej stronie. Odczekaj chwilę i spróbuj ponownie. |
| 503 | `service_unavailable` | Tak | API transcript1 jest chwilowo niedostępne. Ponów request za chwilę. |

Jeśli przeglądarka używa cookie logowania zamiast tokenu bearer, sprawdzamy też origin. Request z innej strony dostanie `403 forbidden_origin`. To sprawdzanie nie dotyczy wywołań API z nagłówkiem `Authorization`.

Przy każdej odpowiedzi `429` nagłówek `Retry-After` podaje czas oczekiwania w sekundach. Konkretne limity znajdziesz w [dokumentacji rozliczeń i limitów](https://transcript1.com/pl/docs/billing-and-limits).

## Kiedy powtórzyć request

- Ponów request bez zmian tylko jeśli `retryable` ma wartość `true`. Dotyczy to `rate_limited`, `too_many_active_jobs`, `internal_error` i `service_unavailable`. Jeśli jest nagłówek `Retry-After`, odczekaj wskazany czas. Jeśli go nie ma, wydłużaj przerwy między próbami.
- Przy ponawianiu `POST /v1/transcriptions` zachowaj ten sam `Idempotency-Key`. Dzięki temu nie zapłacisz drugi raz, jeśli pierwsza próba jednak się udała.
- Przy pozostałych kodach najpierw popraw request, dopiero potem wyślij go ponownie.

## Gdy transkrypcja się nie uda

Błąd może pojawić się już po odpowiedzi API. Jeśli `status` zmieni się na `failed`, w obiekcie transkrypcji znajdziesz `error: { "code", "message" }`. Sprawdzaj pole `error` podczas odpytywania API lub w [webhooku](https://transcript1.com/pl/docs/webhooks) `transcription.failed`.

| `error.code` | Co się stało | Czy próbować ponownie? |
|---|---|---|
| `media_unavailable` | Nagranie nie istnieje lub nie da się już do niego dotrzeć. | Nie. Sprawdź link. |
| `media_private` | Nagranie jest prywatne. | Nie. Podaj publiczny post albo nagranie z YouTube o widoczności publicznej lub niepublicznej (unlisted). |
| `login_required` | Bez logowania platforma nie udostępni nagrania. | Nie. Traktujemy ten błąd jako trwały i nie ponawiamy transkrypcji. |
| `no_audio` | W filmie nie ma ścieżki audio. | Nie. Traktujemy ten błąd jako trwały i nie ponawiamy transkrypcji. |
| `age_restricted` | Nagranie ma ograniczenie wiekowe. | Nie. Zamiast linku wyślij plik. |
| `live_stream` | Transmisja jeszcze trwa lub dopiero ma się zacząć. | Poczekaj, aż transmisja się skończy. |
| `no_captions` | Wybrano `source` o wartości `captions`, ale nie ma napisów, z których można skorzystać. | Zmień ustawienie na `source: "auto"` lub `"stt"`. |
| `media_too_long` | Nagranie przekracza limit 5 godzin dla transkrypcji AI. | Nie. Najpierw podziel nagranie. |
| `unsupported_media` | Pliku nie da się odczytać lub brakuje w nim ścieżki audio. | Nie. Wyślij plik w obsługiwanym formacie. |
| `no_speech` | Nie wykryto mowy. | Nie. |
| `unsupported_language` | Nie obsługujemy języka tego nagrania. | Nie. Podaj obsługiwany kod w `language` lub ustaw `"auto"`. |
| `insufficient_minutes` | Zabrakło minut w momencie rozliczania transkrypcji. | Tak, gdy doładujesz minuty. |
| `fetch_failed` | Mimo kilku prób nie udało się pobrać nagrania. | Tak, spróbuj później. |
| `transcription_failed` | Transkrypcja AI nie powiodła się mimo kilku prób. | Tak, spróbuj później. |

Jeśli transkrypcja się nie uda albo ją anulujesz, nic nie płacisz. Jeśli zdążyliśmy pobrać minuty, zwrócimy je na konto.