Hatalar ve yeniden deneme | transcript1 docs

İ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:

{
  "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`	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.
`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 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 başlatmadan önce adresinizi doğrulayın.
402	`insufficient_minutes`	Hayır	Kullanılabilir bakiyeniz 0 veya işlem için gereken dakikadan az.
402	`no_active_plan`	Hayır	Ücretli planınız aktif değilken ek dakika satın almaya çalıştınız. Bu kod yalnızca panelin ücretlendirme endpoint'inden döner; transkripsiyon endpoint'lerinden dönmez.
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	`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 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.
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.

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 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, internal_error ve service_unavailable. Retry-After varsa belirtilen süreyi bekleyin. Yoksa her denemede bekleme süresini artırın.
POST /v1/transcriptions ç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 dakika harcamazsınız.
Diğer kodlarda önce hatanın nedenini giderin, sonra yeniden gönderin.

İş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 aldığınızda error alanını kontrol edin.

`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.	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.