Hatalar ve yeniden deneme

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

API'nin isteği kabul etmediği durumlar

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, 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 sayfasına bakın.

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.

İş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. Bir çeviri başarısız olursa transcription.translation.failed webhook’u gönderilir; transkript bu yüzden asla başarısız olmaz.

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