# Hatalar ve yeniden deneme

> Hata yanıtlarını okuyun, hata kodlarını kontrol edin ve ne zaman yeniden deneyebileceğinizi öğrenin.

Canonical: https://transcript1.com/tr/docs/errors
Language: tr
Last updated: 2026-11-05

İstek hatası alırsanız API çağrınızı kabul etmemiştir. Transkripsiyon hatasında ise istek kabul edilmiştir, ancak işlem daha sonra başarısız olmuştur. Bu durumda transkripsiyonun `status` alanı `failed` olur.

## Hata yanıtının yapısı

`/v1` çağrılarında istek hatalarını aynı JSON yapısıyla döndürürüz:

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

Uygulamanızda hangi adımı atacağınıza `code` üzerinden karar verin. `message` kullanıcıya gösterebileceğiniz açıklamadır; metni değişebileceği için bu alana göre koşul yazmayın. `retryable` değeri `true` ise aynı çağrı daha sonra çalışabilir.

Bazı hatalarda `retryable` yanında sorunu açıklayan ek alanlar da bulunur:

| Alan | İlgili hata | Açıklama |
|---|---|---|
| `action_url` | `insufficient_minutes`, `no_active_plan`, `topup_needs_user` | Plan seçebileceğiniz veya ek dakika satın alabileceğiniz sayfa. |
| `minutes_needed`, `minutes_remaining` | `insufficient_minutes` | İşlem için gereken dakika ve kullanılabilir bakiyeniz. Gereken süre henüz bilinmiyorsa ilk alan `null` olur. |
| `reason`, `packs` | `topup_needs_user` | Karttan neden ödeme alınmadığı ve istenen paket sayısı. |
| `supported_platforms` | `unsupported_platform` | Kabul edilen platform değerleri: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`. |
| `missing_chunks` | `upload_incomplete` | Sunucuya ulaşmayan parçaların numaraları. |
| `max_bytes` | `media_too_large` | Hesabınızın dosya boyutu limiti, bayt olarak. |
| `params` | `invalid_request` | Gövde veya sorgu doğrulamasında her hatalı alanı ve o alandaki sorunu gösteren nesne. |

## API'nin isteği kabul etmediği durumlar

| HTTP kodu | `code` | Aynı istek tekrar denenebilir mi? | Neden alırsınız? |
|---|---|---|---|
| 400, 422 | `invalid_request` | Hayır | Bir parametre veya gövde alanı eksik ya da geçersiz. Örneğin `diarize` ile `source: "captions"` veya `reuse_recent` ile `webhook_url` birlikte gönderilmiş olabilir. Gövde geçerli JSON değilse de bu kod döner. |
| 422 | `invalid_url` | Hayır | Bağlantı desteklenmiyor veya `platform` ile eşleşmiyor. YouTube, X, TikTok, Instagram, Facebook, Bluesky ya da [Kaynaklar ve seçenekler](https://transcript1.com/tr/docs/sources-and-options) sayfasındaki diğer platformlardan birinin bağlantısını kullanın. |
| 422 | `unsupported_platform` | Hayır | Gönderdiğiniz `platform` değeri desteklenenler arasında değil. |
| 422 | `unsupported_media` | Hayır | Dosyanın uzantısını desteklemiyoruz. |
| 401 | `unauthorized` | Hayır | API kimlik bilginiz eksik, geçersiz, süresi dolmuş veya iptal edilmiş. Geçersiz ya da süresi dolmuş yükleme token'ında da bu kod döner. |
| 403 | `insufficient_scope` | Hayır | OAuth token'ında gereken `transcriptions:read` veya `transcriptions:write` yetkisi yok. |
| 403 | `email_not_verified` | Hayır | E-postanız henüz doğrulanmamış. Transkripsiyon ya da canlı oturum başlatmadan önce adresinizi doğrulayın. |
| 402 | `insufficient_minutes` | Hayır | Kullanılabilir bakiyeniz 0 veya işlem için gereken dakikadan ya da bir canlı oturumun bir başlayan dakikasından az. [Otomatik yükleme](https://transcript1.com/tr/docs/billing-and-limits#auto-top-up) açıksa transcript1 önce yükleme yapmayı dener. Dakikaları `action_url` üzerinden satın alın ya da bir ajanın `POST /v1/topups` veya MCP aracı `top_up` ile satın almasına izin verin. |
| 402 | `no_active_plan` | Hayır | Ücretli planınız aktif değilken ek dakika satın almaya çalıştınız. Bu kod `POST /v1/topups` ve panelin ücretlendirme endpoint'lerinden döner; transkripsiyon endpoint'lerinden dönmez. |
| 402 | `topup_needs_user` | Yalnızca `pending` ve `in_progress` için | `POST /v1/topups` karttan ödeme almadı. Nedeni `reason` alanındadır: `not_allowed` (kimlik bilgisinin ek dakika satın alma izni yok veya sahibi ekip yöneticisi değil), `cap_reached` (ajanlar için aylık limitte yer kalmadı), `card_declined`, `authentication_required` veya `no_card`. Kullanıcı paketleri `action_url` üzerinden satın alabilir. `pending` (ödeme henüz onaylanmadı) ve `in_progress` (başka bir yükleme sürüyor) durumlarında ödeme yine de tamamlanabilir: kullanıcıyı satın almaya yönlendirmek yerine daha sonra aynı `Idempotency-Key` ile tekrar deneyin. |
| 404 | `not_found` | Hayır | Bu transkripsiyon bulunamadı veya başka bir ekibe ait. |
| 409 | `upload_incomplete` | Hayır | Dosyanın bazı parçaları yüklenmemiş. Eksikleri gönderip tamamlama çağrısını tekrarlayın. |
| 409 | `invalid_state` | Hayır | Transkripsiyon yükleme bekleme aşamasında değil. Artık parça gönderemez veya yüklemeyi tamamlayamazsınız. |
| 409 | `session_ended` | Hayır | Canlı oturum bitmiş olduğundan `POST /v1/live/sessions/:id/token` token veremiyor. Bir WebSocket `error` olayı olarak da gönderilir. |
| 422 | `unsupported_language` | Hayır | Canlı oturumun `language` değeri desteklenmiyor. |
| 422 | `unsupported_translation` | Hayır | Canlı oturumun `translate_to` dili desteklenmiyor ya da canlı çeviri kullanılamıyor. |
| 409 | `idempotency_conflict` | Hayır | Aynı `Idempotency-Key` daha önce farklı parametrelerle kullanılmış. |
| 413 | `media_too_large` | Hayır | Dosya, hesabınızın boyut limitini aşıyor. [Dosya yükleme](https://transcript1.com/tr/docs/uploads) sayfasını kontrol edin. |
| 413 | `invalid_request` | Hayır | JSON gövdesi 1 MB'ı aşıyor. Dosya boyutu hatalarında bunun yerine `media_too_large` kullanılır. |
| 429 | `rate_limited` | Evet | Dakikalık istek limitini aştınız. `Retry-After` değerinde belirtilen saniye kadar bekleyin. |
| 429 | `too_many_active_jobs` | Evet | Aynı anda çalışan transkripsiyon veya açık yükleme limitini aştınız. `Retry-After` değerinde belirtilen saniye kadar bekleyin. |
| 429 | `too_many_live_sessions` | Evet | Planınızın eşzamanlı canlı oturumları kullanımda. `Retry-After` değerinde belirtilen saniye (30) kadar bekleyin. |
| 500 | `internal_error` | Evet | Sunucu tarafında bir sorun oluştu. Biraz bekleyip tekrar deneyin. |
| 503 | `service_unavailable` | Evet | transcript1'e şu anda erişilemiyor. Biraz bekleyip tekrar deneyin. |
| 503 | `live_capacity` | Evet | Tüm canlı kapasite kullanımda. `Retry-After` değerinde belirtilen saniye (30) kadar bekleyip oturumu yeniden oluşturun. |
| 503 | `live_unavailable` | Hayır | Canlı transkripsiyon şu anda kullanılamıyor. |

Tarayıcıdan bearer token yerine oturum çereziyle yapılan çağrılarda isteğin geldiği siteyi de kontrol ederiz. Başka bir siteden geliyorsa `403 forbidden_origin` döner. Bu kontrol, `Authorization` başlığıyla yaptığınız API çağrılarını etkilemez.

Tüm `429` yanıtlarında `Retry-After` bulunur. Değer saniye cinsindedir. Hesabınıza uygulanan limitleri [Ücretlendirme ve limitler](https://transcript1.com/tr/docs/billing-and-limits) sayfasından kontrol edebilirsiniz.

## Ne zaman tekrar denemelisiniz?

- Aynı isteği yalnızca `retryable` değeri `true` olduğunda tekrar gönderin: `rate_limited`, `too_many_active_jobs`, `too_many_live_sessions`, `live_capacity`, `internal_error`, `service_unavailable` ve `reason` değeri `pending` veya `in_progress` olan `topup_needs_user`. `Retry-After` varsa belirtilen süreyi bekleyin. Yoksa her denemede bekleme süresini artırın.
- `POST /v1/transcriptions` veya `POST /v1/topups` çağrısını tekrarlarken aynı `Idempotency-Key` başlığını koruyun. İlk çağrı aslında başarılı olduysa böylece ikinci kez ücret ödemezsiniz.
- Diğer kodlarda önce hatanın nedenini giderin, sonra yeniden gönderin.

## Canlı transkripsiyon

`POST /v1/live/sessions` ve diğer canlı endpoint'ler aynı yanıt yapısını kullanır. Yukarıdaki tablodaki canlı kodların yanı sıra `invalid_request`, `unsupported_language`, `insufficient_minutes` ve `email_not_verified` kodları da bunlar için geçerlidir. Oturum oluşturma idempotent değildir; bu yüzden `too_many_live_sessions` ya da `live_capacity` sonrasındaki bir yeniden deneme yeni bir oturum oluşturur.

Oturum oluştuktan sonra sorunlar HTTP hatası olarak değil, WebSocket üzerinde `error` olayları ve kapanış kodları olarak gelir. Tüm olaylar için [Canlı transkripsiyon](https://transcript1.com/tr/docs/live#websocket-protocol) sayfasına bakın.

| Kapanış kodu | Anlamı |
|---|---|
| `1000` | `session.ended` sonrasında normal kapanış. |
| `1011` | Beklenmeyen sunucu hatası. Yeni bir token ile devam edin. |
| `1012` | `reconnect` sonrasında sunucu yeniden başlıyor. Yeni bir token ile devam edin. |
| `4001` | Token geçersiz, süresi dolmuş ya da zaten kullanılmış. |
| `4004` | Oturum bulunamadı ya da zaten bitti. |
| `4008` | Protokol ihlali: tek uzunluklu ya da aşırı büyük bir ses karesi. |
| `4010` | Aynı oturuma yapılan daha yeni bir bağlantıyla değiştirildi. |

`balance_exhausted` ya da `idle_timeout` gibi bir nedenle biten canlı oturum hata sayılmaz: bir bitiş nedeniyle birlikte `session.ended` gönderir ve kaydedilir. Bkz. [Bitiş nedenleri](https://transcript1.com/tr/docs/live#end-reasons).

## İşlem başladıktan sonra oluşan hatalar

API isteği kabul etmiş olsa da transkripsiyon daha sonra başarısız olabilir. `status` değeri `failed` olduğunda nesnede `error: { "code", "message" }` bulunur. Durumu sorgularken veya `transcription.failed` [webhook bildirimi](https://transcript1.com/tr/docs/webhooks) aldığınızda `error` alanını kontrol edin. Bir çeviri başarısız olursa `transcription.translation.failed` webhook’u gönderilir; transkript bu yüzden asla başarısız olmaz.

| `error.code` | Ne oldu? | Ne yapmalısınız? |
|---|---|---|
| `media_unavailable` | Video bulunamadı veya artık erişilemiyor. | Aynı bağlantıyla tekrar denemeyin; URL'yi kontrol edin. |
| `media_private` | Video gizli. | Aynı videoyu tekrar göndermeyin. Herkese açık bir gönderi kullanın; YouTube'da liste dışı videolar da çalışır. |
| `login_required` | Platform videoyu izlemek için giriş yapılmasını istiyor. | Kalıcı bir hatadır; tekrar denemeyiz. |
| `no_audio` | Videoda ses kanalı yok. | Kalıcı bir hatadır; tekrar denemeyiz. |
| `age_restricted` | Videoda yaş kısıtlaması var. | Aynı bağlantıyı tekrar göndermek yerine dosyayı yükleyin. |
| `live_stream` | Yayın devam ediyor veya henüz başlamamış. | Yayın sona erdikten sonra deneyin. |
| `no_captions` | `source` için `captions` seçilmiş, ancak kullanılabilir altyazı bulunamamış. | `source: "auto"` veya `"stt"` ile gönderin. |
| `media_too_long` | Kayıt, STT için geçerli 5 saat sınırını aşıyor. | Aynı kaydı tekrar göndermeyin; daha kısa parçalara bölün. |
| `unsupported_media` | Dosyayı okuyamadık veya dosyada ses kanalı yok. | Desteklenen bir dosya hazırlayıp gönderin. |
| `no_speech` | Konuşma algılanmadı. | Tekrar denemeyin. |
| `unsupported_language` | Kayıttaki dili desteklemiyoruz. | Aynı ayarla tekrar denemeyin. `language` için desteklenen bir kod veya `"auto"` seçin. |
| `insufficient_minutes` | Ücret hesaplanmadan önce dakika bakiyeniz tükendi ve otomatik yükleme açık olsa bile yeni dakika ekleyemedi. | Ek dakika yükledikten sonra deneyin. |
| `fetch_failed` | Birkaç kez denememize rağmen kaydı indiremedik. | Daha sonra tekrar deneyebilirsiniz. |
| `transcription_failed` | Birkaç kez denememize rağmen STT tamamlanamadı. | Daha sonra tekrar deneyebilirsiniz. |

Transkripsiyon başarısız olursa veya iptal edilirse ücret ödemezsiniz. Daha önce dakika düşülmüşse hesabınıza geri ekleriz.