İYS API Hata Kodları: Anlamları, Çözümleri ve Tekrar Deneme Kuralları

Hatalar nasıl döner?

İYS API metotlarının çoğu hata durumunda bir errors dizisi döner; her öğede code ve message bulunur. Jeton servisi OAuth biçimini kullanır, ViA PASS metotları ise errorCode ve errorMessage alanlarıyla yanıt verir.

// İYS API metotları (izin, bayi, sorgu vb.)
{ "errors": [ { "code": "H175", "message": "İlk defa kaydedilen bir iznin durum (status) bilgisi RET olmamalıdır." } ] }

// /oauth2/token (OAuth biçimi)
{ "error": "invalid_request", "error_description": "Kullanıcı kimlik bilgileri geçersiz." }

// ViA PASS metotları
{ "errorCode": "ERR-SYS-0004", "errorMessage": "..." }

• HTTP durumu da anlam taşır: 400 ve 422 veri hatası, 401 kimlik, 403 yetki ve abonelik, 429 limit, 500 ve 503 sunucu tarafı sorunudur.
• Toplu eklemede hata, ilk yanıtta değil sonuç sorgusunda gelir. GET .../consents/request/{requestId} yanıtında her alt istek için status: "failure" ve bir error nesnesi döner.
• X-Trace-Id: 19/10/2026 tarihli 3.2.3 sürümünden beri tüm yanıtlarda bu başlık var. İstek, yanıt ve X-Trace-Id değerini birlikte loglayın; destek başvurusunda bunları iletmeniz isteniyor.

İş kuralı hataları: H174, H175, H178, H467 ve diğerleri

Bu gruptaki hatalar isteğin biçimi doğru olsa bile İYS'deki kayıtla ya da mevzuatla çeliştiğini gösterir.

H174: Aynı durumla güncelleme

ONAY durumundaki bir izne tekrar ONAY, RET durumundakine tekrar RET gönderdiğinizde gelir. Çoğu zaman sizin sisteminizle İYS'nin zaten aynı durumda olduğunu gösterir. Mutabakat ve eşitleme işlerinde bu kodu "değişiklik gerekmiyor" olarak ele alın, ama emin olmak için consents/status ile kaydı sorgulayın.

H175: İlk kayıt RET olamaz

İYS'de hiç kaydı olmayan bir adres için ilk hareket RET olamaz. Kendi veritabanınızda "pazarlama istemiyor" olarak işaretli ve İYS'de hiç kaydı olmayan kişiler için yapılacak iş, onlara ticari ileti göndermemektir. Bu kişileri İYS'ye ONAY olarak yüklemek ise hem yanlış hem de risklidir.

H178: Eski tarihli güncelleme

İYS, sistemdeki iznin tarihinden önceki tarihli bir hareketle güncelleme kabul etmez. İYS SSS'ye göre kayıtlı bir izin aynı consentDate ile yeniden yüklendiğinde de H178 alınır; SSS bu durumda consentDate değerinin sistemdekinden farklı olacak şekilde güncellenmesini söyler. Pratikte en sık sebep, kuyruktaki hareketlerin sırasız gönderilmesidir. Hareketleri consentDate sırasıyla gönderin. Tarihi de iznin gerçekte alındığı ya da reddedildiği an olarak yazın; yapay tarih üretmeyin, çünkü İYS SSS izin verilen tarihle işlem yapılmamasının şikâyet riski doğurabileceğini belirtiyor.

H467: Üç iş gününden eski izin

Yönetmelik m.7/11'e göre İYS üzerinden alınmayan onaylar hizmet sağlayıcı tarafından üç iş günü içinde İYS'ye kaydedilir, m.7/12'ye göre kaydedilmeyen onaylar geçersizdir. API bu kuralı H467 ile uygular. İYS SSS'ye göre cumartesi, pazar ve resmî tatiller iş gününden sayılmaz. Yeni bir TACIR izni eklenirken bu kural yoktur; TACIR izni güncellenirken devreye girer. Bu hata tekrar denemeyle düzelmez. Onay kuyruğunuzu günlük değil, mümkünse anlık ya da saatlik işleyin ve takılan kayıtlar için alarm kurun. Onay kayıtlarını nasıl saklayacağınızı onay kaydı saklama ve ispat yazısında anlattık.

Format ve doğrulama hataları

Kimlik, yetki ve abonelik hataları

Canlı ortamda 401 alıyorsanız İYS SSS'nin önerdiği ilk kontrol IP'dir: istek attığınız IP adresi İYS'de tanımlı olmalıdır. Paket ve kota konuları için İYS ücret tarifesi yazısına bakabilirsiniz.

Limit ve sunucu hataları

Tekrar denensin mi? Karar kuralı

İYS dokümanında genel bir tekrar deneme politikası yer almıyor, ama birkaç kural kararı netleştiriyor. 429 ve bazı 5xx mesajları açıkça "daha sonra tekrar deneyiniz" diyor. Öte yandan canlı ortamda son 24 saatte 20.000 ve üzeri istekte başarı oranı %70'in altına düşerse ve bildirimden sonraki 96 saatte düzelmezse IP adresiniz whitelist'ten çıkarılır. Bu hesaba 400, 401, 403, 404 ve 422 yanıtları girer. Yani hatalı veriyi tekrar tekrar göndermek hem sonuç vermez hem de erişiminizi riske atar.

// HTTP durumu ve İYS koduna göre ne yapılacağına karar veren basit yardımcı
function hataKarari(status, kod) {
  if (status === 429) return 'BEKLE';            // limit doldu: pencere bitene kadar bekleyin
  if (status === 401 && kod === 'H351') return 'JETON_YENILE'; // jetonu yenileyip bir kez deneyin
  if (status >= 500 || kod === 'H123') return 'SONRA_DENE';    // artan aralıklarla, sınırlı sayıda
  if (kod === 'H174') return 'ZATEN_BU_DURUMDA';  // sorgulayıp doğrulayın, tekrar göndermeyin
  return 'DUZELT';                                // 400/403/404/422: veri, yetki veya abonelik sorunu
}

5xx sonrasında isteğin İYS'de işlenip işlenmediğinden emin değilseniz, tekrar göndermeden önce consents/status ile kaydı sorgulayın. 3.1.1 sürümüyle gelen V2 tekil ekleme metodu da yardımcı olur: aynı gövde değiştirilmeden tekrar gönderilirse aynı transactionId döner. Toplu eklemede ise boş sonuç bir hata değildir; işlem henüz bitmemiştir ve sonucu en az 300 saniye sonra sorgulamanız gerekir. Bekleme ve kuyruk tasarımı için API rate limiting stratejileri yazısına bakabilirsiniz.

ViA ile ilgili sık hatalar

İYS üzerinden onay toplama hizmeti ViA'nın kendi hata kodları var. En sık karşılaşılanlar şunlar:

• H1015: İşleme devam edebilmek için ViA kontör miktarı yeterli değil.
• H1050: OTP kodu en fazla 3 defa hatalı girilebilir.
• H465: Alıcı için 3 dakika içinde yeni bir süreç başlatılamaz.
• H1000: Form yayımlanmadığı için süreç başlatılamaz.

ViA akışının tamamını İYS ViA nedir yazısında anlattık.

Sürüm notlarından öne çıkanlar

• 3.2.3 (19/10/2026): Tüm yanıtlara X-Trace-Id başlığı eklendi.
• 3.2.2 (13/10/2026): ViA FORM metotları eklendi.
• 3.1.3 (18/11/2025): Hata kodlarına H486 (geçersiz source) eklendi.
• 3.1.1 (21/08/2025): Tekil İzin Ekleme V2 ve Asenkron Çoklu İzin Ekleme V2 metotları eklendi.
• 1.1.3 (22/01/2021): Üç iş günü kuralı (H467) API'ye eklendi.

Eski açık kaynak istemciler V2 metotlarını, push servisini veya H467 gibi sonradan eklenen kuralları içermeyebilir. Hata yönetimini her zaman resmî dokümana göre yazın.

Destek başvurusunda ne gönderilir?

İYS dokümanına göre destek başvurusunda HTTP metodu, tam URL, saniye hassasiyetinde ve saat dilimli istek zamanı, istek gövdesi, yanıt kodu ve gövdesi, X-Trace-Id ve çıkış IP adresi iletilmelidir. Jeton ve şifre paylaşılmamalıdır. Başvuru, API Destek Platformu'na kayıtlı e-posta adresinden destek@iys.org.tr adresine yapılır. Entegratör kullanıyorsanız önce entegratörünüzle iletişime geçmeniz genellikle daha hızlı sonuç verir.

Sık Sorulan Sorular

Toplu eklemede 202 aldım ama izin görünmüyor, neden?

202 ve subRequestId yalnızca isteğin kuyruğa alındığını gösterir. İYS SSS de bunun iznin eklendiği anlamına gelmediğini söylüyor. Sonucu requestId ile sorgulayın; failure satırlarındaki hata kodları sorunu gösterir.

H178 alıyorum ama tarihim doğru, neden?

Aynı consentDate ile kayıtlı bir izni yeniden yüklediğinizde de H178 alırsınız. Ayrıca sistemdeki kayıttan daha eski tarihli bir hareket gönderiyor olabilirsiniz. Önce mevcut kaydı sorgulayın, sonra hareketleri tarih sırasıyla gönderin.

H467 hafta sonu ve bayramda nasıl hesaplanır?

İYS SSS'ye göre cumartesi, pazar ve resmî tatiller iş günü sayılmaz. Yine de son güne bırakmak yerine onayları alındıkları gün göndermek en güvenli yoldur.

429 aldığımda ne kadar beklemeliyim?

Saniyelik limitte (H083, H124) kısa bir bekleme yeterlidir. Saatlik limitlerde (H084, H086, H089) pencere dolmadan o servise istek atmayın; jeton servisinde süre dolmadan atılan istek sayacı yeniden başlatır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: İYS nedir · İYS API entegrasyonu · İYS ViA nedir · İYS entegratörü nedir · İYS ret bildirimi · REST API güvenlik rehberi