Hatalar — Hear2Text API

Hata gövdesi

Bu API’de reddedilen her istek, sebebi ne olursa olsun aynı iki alanı taşır. Ayrıca ele almanız gereken ikinci bir hata biçimi yok.

Herhangi bir 4xx ya da 5xx

{
  "error": "insufficient_scope",
  "message": "This key does not carry the scope this endpoint needs.",
  "required": "transcriptions:write"
}

error sabit ve makinenin okuyabileceği koddur. Akışınızı buna göre dallandırın.
message log okuyan bir insan için yazılır. Ayrıştırmayın; ifadesi her an değişebilir.
Bazı hatalar bir alan daha taşır: doğrulama hatasında errors, kapsam reddinde required, erişimi kesen 403’lerde docs.

Katalog

API’nin verebileceği bütün kodlar. Bu liste, API’nin karşısında test edildiği OpenAPI belgesinden üretilir; yani çalışan koddan ayrı düşemez.

HTTP	`error`	Anlamı
401	`missing_api_key`	Authorization başlığı yok. `Authorization: Bearer h2t_live_…` gönderin.
401	`invalid_api_key`	Anahtar okunamıyor, tanınmıyor ya da iptal edilmiş; başka bir yerin kimlik bilgisi de olabilir. Yeniden denemenin faydası yok.
403	`subscription_required`	Hesabın etkin aboneliği yok. Anahtar duruyor; abonelik geri geldiğinde yeniden çalışır.
403	`insufficient_scope`	Anahtar, bu endpointin istediği kapsamı taşımıyor. Hangi kapsam olduğunu gövde yazar; o kapsamla yeni bir anahtar oluşturun.
403	`account_restricted`	Hesap kısıtlanmış. Destek ekibiyle iletişime geçin.
403	`guest_account_not_supported`	Misafir hesaplar API’yi kullanamaz.
403	`workspace_scope_mismatch`	Bu anahtar bir çalışma alanına sabitlenmiş, kayıt ise başka bir alanda.
403	`forbidden`	Sormaya yetkiniz var, bu kayda bunu yapmaya yok.
404	`not_found`	Böyle bir kayıt yok ya da bu anahtarın göremeyeceği bir kayıt. İkisi bilerek ayırt edilemiyor.
409	`concurrency_limit`	Planın aynı anda işleyebileceğinden fazla kayıt çalışıyor. Biri bitene kadar bekleyin.
409	`idempotency_key_reused`	Bu Idempotency-Key daha önce başka bir gövdeyle kullanılmış. Yeni bir değer üretin.
409	`idempotency_request_in_progress`	Aynı Idempotency-Key ile gelen ilk istek henüz yanıtlanmadı. Birkaç saniye sonra tekrar deneyin.
409	`transcription_still_processing`	Henüz bitmemiş bir kayıt, yani sırada bekleyen ya da işlenmekte olan bir kayıt silinemez. Tamamlanmasını ya da başarısız olmasını bekleyin.
409	`transcription_is_not_ready`	Yalnızca tamamlanmış bir kayıt dışa aktarılabilir.
413	`file_too_large`	İstek gövdesi sunucunun hiç kabul etmediği bir büyüklükte. Kaydı sıkıştırın ya da bölün. Sunucuya ulaşan ama dosya başına tavanı aşan bir dosyanın karşılığı ise `file` alanını gösteren bir `validation_failed` olur.
400	`bad_request`	İstek, anlayabildiğimiz bir HTTP isteği olarak okunamadı. Aynı haliyle yeniden denemenin anlamı yok.
405	`method_not_allowed`	Bu yol var, ama bu HTTP yöntemiyle değil. API referansına bakın.
422	`validation_failed`	İstek geldiği haliyle kabul edilemedi. Hangi alanda ne olduğu `errors` içinde.
422	`uploaded_file_cannot_be_processed`	Yükleme depolamaya sağlam ulaşmadı. Yeni bir Idempotency-Key üretip baştan gönderin.
422	`playlist_not_acceptable`	Bu bağlantı bir oynatma listesi. Tek seferde tek kayıt gönderin.
429	`rate_limited`	Çok fazla istek geldi ya da bugünün kayıt açma hakkı bitti. Retry-After kadar saniye bekleyin.
500	`internal_error`	Hata bizde. Araları açarak yeniden deneyin; sürerse X-Request-Id’yi bize iletin.
503	`service_unavailable`	API kısa bir süreliğine kapalı, çoğunlukla bir sürüm yüklenirken. Retry-After kadar ya da biraz sonra yeniden deneyin.

Doğrulama hataları

422 yanıtında bir errors nesnesi gelir: hangi alanda sorun varsa onun adı ve o alanla ilgili bütün mesajlar.

422 Unprocessable Entity

{
  "error": "validation_failed",
  "message": "The request could not be accepted as sent.",
  "errors": {
    "url": ["Send either a `file` or a `url`."],
    "language": ["Unknown language code. GET /languages lists the ones we accept."]
  }
}

İstek id’leri

Her yanıt — hata yanıtları dahil — X-Request-Id taşır. Kendi id’nizi gönderirseniz aynısını döneriz, göndermezseniz biz üretiriz. Bu id loglarımızda isteğin yanında durur; destek yazışmasında onu vermeniz herkese bir gün kazandırır.

Neyi yeniden denemeli

Durum kodu	Denenir mi?
`401`, `403`, `404`, `413`, `422`	Hayır. Beklemek yanıtı değiştirmez; isteği ya da anahtarı düzeltin.
`409`	Evet, ama hemen değil. Kayıtlar bittikçe aynı anda işleme sınırı boşalır; yanıtlanmayı bekleyen bir Idempotency-Key ise saniyeler içinde sonuçlanır.
`429`	Evet, `Retry-After` kadar saniye bekledikten sonra. Daha erken değil.
`5xx`	Evet, araları açarak. Oluşturma isteğiyse aynı `Idempotency-Key` ile; böylece tek kayıt için iki kez ödemezsiniz.