# 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-10-19

İ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` | 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](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 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](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. |
| 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](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`, `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](https://transcript1.com/tr/docs/webhooks) 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.