- API istek hataları — senkron bir API çağrısına verilen HTTP yanıtı (kimlik doğrulama, faturalama, hatalı biçimlendirilmiş istekler, bulunamayan kaynaklar). Bkz. API istek hataları.
- Prediction hata kodları — istek kabul edilip kuyruğa alındı, ancak prediction’ın kendisi
status: "failed"ile sonuçlandı. Hata, prediction üzerindekierrornesnesiyle tanımlanır; bu nesneyi prediction status uç noktalarından, webhook teslimatlarından ve result uç noktasından alırsınız. Bkz. Prediction hata kodları.
Prediction hata kodları
Başarısız olan bir prediction birerror nesnesi taşır:
Başarısız olan predictions için ücret alınmaz; istek için ayrılan krediler serbest bırakılır.
Başarısız olmamış bir prediction
error: null taşır. 17 Ağustos 2026’dan önce entegrasyon yaptıysanız bkz. Geçiş notu.
Hatanın size ulaştığı yerler
Aynıerror nesnesi her kanalda yayımlanır; dolayısıyla onu zaten baktığınız yerde okuyabilirsiniz:
result uç noktasından bir hatayı okuma
Başarısız olmuş bir prediction’ın çıktısını istemek, buna yol açan hatayı taşıyan bir400 döndürür; istek düzeyindeki kod PREDICTION_FAILED’dir:
error.codedeğeriPREDICTION_FAILED’dir; bu bir API istek hatası olup “çıktısını istediğiniz prediction bir çıktı üretmedi” anlamına gelir;error.detailsise prediction’ın kendierrornesnesidir — aynı istek için/status’un bildirdiğiyle birebir aynıdır, dolayısıyla iki uç nokta hatanın nedeni konusunda asla çelişemez. Dallanmayıerror.details.reasonveerror.details.retryableüzerinden yapın.
error.message, prediction’ın mesajını yineler; böylece yalnızca en üst düzeydeki mesajı okuyan bir istemci de işine yarayacak bir şey alır.
İki timestamp, iki anlam. En üst düzeydeki timestamp bu HTTP yanıtının üretildiği andır; error.details.timestamp ise prediction’ın başarısız olduğu andır. Günler sonra çektiğiniz bir prediction’da ikisi günlerce ayrı düşer. Hatanın zamanını kastediyorsanız her zaman içtekini okuyun.
Resmî istemci kitaplıkları bunu sizin için açar: result(), code, reason ve retryable alanları prediction’ın kendi değerleri olan bir hata fırlatır; bunlar aynı hata için subscribe()’ın fırlattıklarıyla birebir aynıdır.
Hâlâ kuyrukta bekleyen ya da çalışan bir prediction, veya iptal edilmiş olan bir prediction, öteden beri döndürdüğü aynı genel 400 yanıtını döndürmeye devam eder.
Yeniden denenip denenmeyeceğine karar verme
retryable değerini okuyun. Tam olarak tek bir soruyu yanıtlar — bu isteğin aynısını yeniden göndermek farklı bir sonuç verir mi? — ve code’dan bağımsızdır: aynı code bir hatada yeniden denenebilir, bir başkasında denenemez olabilir.
retryable isteğe bağlıdır. Bulunmadığında, aşağıdaki tablodaki code bazlı varsayılana geri dönün. Bu alan var olmadan önce Sunra’nın davranışı buydu; dolayısıyla bu geri dönüş her zaman güvenlidir, yalnızca daha az kesindir.
code
reason
reason, code’un arkasındaki belirli nedeni adlandırır. Bunu metrikler, yönlendirme ve destek teşhisi için kullanın; yeniden deneme kararı için retryable’ı kullanın.
Bugün yayımlanan her reason’ın aşağıda kendi bölümü var ve bağlantı çapası reason’ın kendisi — #input_fetch_failed, #moderation_blocked gibi — böylece bir hata raporu doğrudan anlamına bağlanabilir.
input_validation_failed
code: invalid_input · retryable: false
İstek, Sunra’nın kendi schema veya parametre doğrulamasından geçemedi. message sorunlu alanı adıyla belirtir.
Ne yapmalı: adı verilen alanı düzeltin. Aynı istek başarısız olmaya devam eder.
provider_rejected_input
code: invalid_input · retryable: false
Model provider bir veya daha fazla girdi parametresini reddetti. Provider hangisi olduğunu bize bildirdiğinde message bunu aktarır; bazı providers yalnızca girdinin kabul edilemez olduğunu bildirir ve o durumda tahmin yürütmek yerine tam olarak bunu söyleriz.
Ne yapmalı: parametrelerinizi modelin schema’sıyla karşılaştırarak gözden geçirin — aralık dışı bir değer, desteklenmeyen bir birleşim, modelin kabul etmediği bir en-boy oranı ya da süre.
input_fetch_failed
code: invalid_input · retryable: false veya true
URL ile belirtilen bir girdi dosyası indirilemedi. retryable değerinin gerçekten değiştiği tek reason budur; bu yüzden varsaymak yerine alanı okuyun:
false— karşı taraf bizi geri çevirdi: bir4xx, indirmemize izin verilmeyen bir adres, bir yönlendirme ya da boyut sınırını aşan bir dosya;true— karşı tarafa o an ulaşılamadı: bir5xx, bir zaman aşımı ya da bir DNS hatası.
message, hangi girdinin başarısız olduğunu anlayabilmeniz için gönderdiğiniz URL’yi yansıtır — query string’i kaldırılmış olarak, böylece presigned URL içinde taşınan kimlik bilgileri size asla geri yansıtılmaz:
retryable false olduğunda URL’nin herkese açık şekilde erişilebilir olduğunu ve presigned bir bağlantının süresinin dolmadığını doğrulayın. true olduğunda yeniden deneyin.
moderation_blocked
code: unsafe_content · retryable: false
Model provider’ın içerik güvenliği sistemi tarafından engellendi — ister giren prompt ve girdi medyası, ister geri dönen üretilmiş çıktı olsun.
Ne yapmalı: prompt’u veya medyayı değiştirin. Aynı içeriği yeniden göndermek yine engellenir.
provider_rate_limited
code: service_provider_error · retryable: true
Model provider istekleri hız sınırlamasına tabi tutuyor.
Ne yapmalı: geri çekilme (backoff) ile yeniden deneyin ya da başka bir modele yönlendirin.
provider_unavailable
code: service_provider_error · retryable: true
Model provider isteği karşılayamadı.
Ne yapmalı: daha sonra yeniden deneyin ya da başka bir modele yönlendirin.
provider_timeout
code: task_timeout · retryable: true
prediction izin verilen süre içinde tamamlanmadı.
Ne yapmalı: yeniden deneyin — yükün düşük olduğu bir zaman dilimi ya da daha küçük bir istek (daha kısa süre, daha düşük çözünürlük) olasılığı artırır.
provider_account_error
code: internal_server_error · retryable: false
Model provider nezdindeki kendi hesabımızda bir sorun var — faturalama, kimlik bilgileri ya da kalıcı bir kota. Bu bizden kaynaklanıyor, girdinizden değil.
Ne yapmalı: sizin tarafınızda yapılacak bir şey yok; yeniden denemek işe yaramaz, uyarı bize otomatik olarak ulaşır. Bu kapasiteye hemen ihtiyacınız varsa başka bir modele yönlendirin.
endpoint_misconfigured
code: internal_server_error · retryable: false
Bu model uç noktası bizim tarafımızda yanlış yapılandırılmış.
Ne yapmalı: sizin tarafınızda yapılacak bir şey yok; yeniden denemek işe yaramaz, uyarı bize otomatik olarak ulaşır. Acilse request_id ile destek ekibine başvurun.
queue_enqueue_failed
code: internal_server_error · retryable: true
prediction kuyruğa alınamadı.
Ne yapmalı: isteği yeniden gönderin.
reaped_stalled
code: internal_server_error · retryable: true
prediction takıldı ve sonlandırıldı.
Ne yapmalı: isteği yeniden gönderin.
Bilinmeyen değerler
Hemcode hem de reason açık kümedir. Daha fazla hatayı sınıflandırdıkça, kırıcı değişiklik duyurusu yapılmadan yeni değerler eklenir. Entegrasyonunuz tanımadığı bir değerle karşılaştığında çökmemeli, hatayı yok saymamalı ve payload’ı reddetmemelidir.
- Bilinmeyen
reason—reasonyokmuş gibi davranın ve kararıretryable(ya dacodebazlı varsayılan) ile verin. Ham değeri günlüklerinizde saklayın; destek ekibinin hatayı tespit etmesinin en hızlı yolu budur. - Bilinmeyen
code—internal_server_errorolarak değerlendirin. Adıyla bilmeye değer bir nöbetçi değer var:unknown_error_code. Sunra bunu, bir prediction başarısız olduğu halde onun için hiçbir sınıflandırma elde edilemediğinde gönderir.
Geçiş notu: hata yokken error değeri null olur
17 Ağustos 2026 itibarıyla geçerlidir. error nesnesinin her kanalda tek bir temsili var. Aralarındaki üç fark ortadan kalktı:
- prediction başarısız olmadığında
errordeğerinull’dır.GET /v1/predictions/{prediction_id}, başarıyla tamamlanan, kuyrukta bekleyen ve iptal edilen her prediction için eskiden boş bir nesneyle —"error": {}— yanıt veriyordu. Artık, kuyruk durum uç noktasının zaten yaptığı gibi,"error": nullyanıtını veriyor. Boşluk sınaması yapıyorsanız (Object.keys(response.error).length === 0), bunu bir null denetimiyle (response.error === null) değiştirin. - Bir başarısızlık her zaman boş olmayan bir
codevemessagetaşır. Başarısızlık, sınıflandıramadığımız bir şey kaydettiyse artık eksik, boş ya da string olmayan bir alan yerineunknown_error_codenöbetçi değerini ve genel bir mesaj alırsınız. - Düz metin olarak kaydedilmiş başarısızlıklar size metin olarak ulaşır. Nisan 2026’ya ait bir avuç prediction, hatasını çıplak bir string olarak saklamıştı.
GET /v1/predictions/{prediction_id}bunu eskiden atıyordu, kuyruk durum uç noktası ise nöbetçi mesajla değiştiriyordu; artık ikisi de bunucode: "unknown_error_code"altındamessageolarak yayımlıyor.
error bu yanıtların zaten hepsinde vardı, yalnızca değeri değişti. Webhook teslimatlarına dokunulmadı — diğer kanalların üzerinde birleştiği biçim zaten onlarınkiydi — ve error, succeeded bir teslimatta null olarak gönderilmek yerine bulunmamaya devam ediyor.
Uyumluluk penceresi. İkili yayım dönemi yok; API o tarihte "error": {} üretmeyi bıraktı. O tarihten önce yakaladığınız payload’ları yeniden oynatıyor ya da yeniden işliyorsanız, saklı bu veriler tedavülden kalkana kadar null ile {} değerlerini aynı şey olarak değerlendirin.
Yaklaşan değişiklik: bazı hatalar daha spesifik bir code alacak
Bugün hataların büyük bir bölümü service_provider_error olarak raporlanıyor; bunların çoğu ne geçici ne de provider’ın kusuru. Providers’ı teker teker sınıflandırdıkça, bu hatalar kendilerini gerçekten tanımlayan code’a taşınıyor:
- bir provider’ın girdinizi deterministik biçimde reddetmesi
invalid_inputoluyor (öncedenservice_provider_error); - Sunra tarafındaki bir sorun, örneğin yanlış yapılandırılmış bir uç nokta ya da kendi provider hesabımız,
internal_server_erroroluyor (öncedenservice_provider_error); - indiremediğimiz bir girdi dosyası
invalid_inputoluyor (öncedeninternal_server_error).
code değeri eklenmiyor — yukarıdaki beş değer sınıflandırılmış kodların tamamı olmayı sürdürüyor. Değişen şey, belirli bir hatanın bunlardan hangisini alacağıdır ve bu, provider bazında kademeli olarak gerçekleşir. code üzerinden dallanıyorsanız, bu mantığı retryable ve reason üzerine taşımak için iyi bir zaman: bu ikisi hatayı doğrudan tanımlar ve yeniden sınıflandırmadan etkilenmez.