Sabit neden kodu
Sabit bir hata kodu istemci mantığında, raporlamada ve taleplerin otomatik yönlendirilmesinde kullanılır.
Dokümantasyon / API Hataları
API hata yönetimi
iGaming entegrasyonları için yanıtları, hata kodlarını, geçici kesintileri, bilinmeyen sonuçları, teşhisi ve güvenli kurtarmayı kapsayan birleşik model.
HTTP
istek sonucu
Kodlar
açık neden
Tekrar
güvenli eylem
İzleme
istek teşhisi
Hata yönetimi döngüsü
API yanıtından kurtarmaya
01
Sonuç türünü belirleyin
HTTP durumunu, neden kodunu, hata kategorisini ve işlem durumunu kontrol edin.
02
İnceleme için verileri kaydedin
İstek ve işlem kimliklerini, endpoint'i, zamanı, sağlayıcı referansını ve güvenli parametreleri kaydedin.
03
Güvenli bir eylem seçin
Verileri düzeltin, işlemi durdurun, bir süre sonra tekrar deneyin veya mevcut durumu kontrol edin.
04
Kurtarın ve doğrulayın
Yinelenen işlemleri önleyin, sonuçların mutabakatını yapın, sorumlu ekipleri bilgilendirin ve temel nedeni kapatın.
Genel bakış
Bir hata nedeni ve sonraki eylemi açıklamalıdır
Tek başına HTTP 400 veya 500 yanıtı yeterli değildir. Güvenilir bir API sabit bir neden kodu döndürür, yanıtı bir istek kimliğiyle ilişkilendirir ve verilerin düzeltilmesi, işlemin durdurulması, isteğin tekrar gönderilmesi veya durumun ayrıca kontrol edilmesi gerektiğini açıkça gösterir.
Öngörülebilir eylem
Hata kategorisi isteğin tekrar gönderilip gönderilemeyeceğini ve hangi verilerin değiştirilmesi gerektiğini gösterir.
Teşhis korelasyonu
İstek, işlem ve sağlayıcı kimlikleri istemci günlüklerini dahili sistemler ve destekle ilişkilendirir.
Hata yapısı
Önerilen hata yanıtı yapısı
Yanıt; dahili uygulamayı veya hassas verileri açığa çıkarmadan kompakt, sabit ve otomatik işlemeye uygun olmalıdır.
Hata kodu
Açıklayıcı mesaj düzenlense bile değişmeyen, nedeni tanımlayan sabit kimlik.
Açıklama
Dahili kod, veritabanı sorguları, gizli bilgiler veya gereksiz ayrıntılar içermeyen kısa ve güvenli açıklama.
İstek ID'si
İşlemi günlüklerde bulmak ve destekle iletişim kurmak için benzersiz kimlik.
Ek veriler
İzin verilen durum, limit, mevcut durum veya reddetme için güvenli neden.
Tekrar denenebilir
İşlemin yinelenen sonuçlara karşı korunmasını ortadan kaldırmayan, geçici hatayı açıkça belirten işaret.
Tekrar denemeden önce bekleme
İstek sıklığı sınırı ve geçici kullanılamama için saniye cinsinden önerilen gecikme veya HTTP header'ı.
Alan hataları
Neden kodu, değer yolu ve güvenli açıklamayla birlikte sorunlu alanların listesi.
Dokümantasyon referansı
Nedeni ve nasıl düzeltileceğini açıklayan kalıcı bağlantı veya bölüm kimliği.
Hata kategorileri
Temel hata kategorileri
HTTP durumu genel sonuç sınıfını gösterirken dahili kod belirli nedeni ve izin verilen eylemi açıklar.
Girdi doğrulama hatası
Geçersiz format, eksik zorunlu alan, desteklenmeyen değer, tutar hassasiyetinin hatalı olması veya geçersiz istek yapısı.
Kimlik doğrulama hatası
Eksik, süresi dolmuş veya geçersiz token, API anahtarı, imza, istek zaman damgası veya nonce.
Yetersiz yetki
İstemci tanınmıştır ancak eylem için gerekli role, markaya, pazara veya izne sahip değildir.
Nesne bulunamadı
Oyuncu, ödeme, tur, KYC kontrolü, sağlayıcı veya başka bir nesne mevcut değildir ya da istemci tarafından erişilebilir değildir.
Durum çakışması
Nesnenin sürümü veya durumu değişmiştir ya da işlem kimliği daha önce farklı parametrelerle kullanılmıştır.
İş kuralı ihlali
Yetersiz bakiye, aşılmış limit, engellenmiş oyuncu, yasak pazar veya geçersiz durum geçişi.
Çok fazla istek
İstemci, yöntem, rol veya kritik işlem için izin verilen istek sayısı aşılmıştır.
Sağlayıcı kullanılamıyor
Harici hizmet kullanılamıyor, yavaş yanıt veriyor veya geçici olarak işlem kabul etmiyor.
Dahili hata
Dahili ayrıntıları açığa çıkarmayan ancak teşhis için bir kimlik içeren beklenmeyen platform hatası.
Tekrarlar ve kurtarma
İsteği tekrar gönderme ve bilinmeyen sonuç
Tekrar deneme ancak hata türü belirlendikten ve ilk işlemin zaten tamamlanmış olabileceği kontrol edildikten sonra güvenlidir.
01
Tekrara izin verilip verilmediğini kontrol edin
Veri, yetki ve iş kuralı hataları genellikle isteğin tekrar gönderilmesi yerine düzeltilmesini gerektirir.
02
Aynı işlem anahtarını koruyun
Finansal, oyun veya başka kritik bir işlemin tekrarı yeni bir sonuç oluşturmamalıdır.
03
Denemeler arasındaki süreyi artırın
Aralıklar kademeli olarak artırılır, sunucunun belirttiği bekleme süresine uyulur ve toplam deneme sayısı sınırlandırılır.
04
Durdurun ve inceleme için yönlendirin
Tüm denemeler tükendiğinde işlem tamamlanmamış olarak kaydedilir ve manuel incelemeye veya mutabakata gönderilir.
Yanıt alınmaması işlemin başarısız olduğu anlamına gelmez
İstek gönderildikten sonra bağlantı kesilirse sonuç bilinmeyebilir. Tekrar denemeden önce işlem kimliğiyle durumu kontrol edin veya güvenilir bir bildirim bekleyin.
Teşhis ve kontrol
Günlükler, kimlikler, metrikler ve uyarılar
Teşhis, gereksiz hassas verileri saklamadan platform, adaptör ve harici sağlayıcı arasındaki istek yolunu yeniden oluşturabilmelidir.
İnceleme bağlamı
İstek, korelasyon, işlem ve harici sağlayıcı kimlikleri.
Endpoint, HTTP yöntemi, ortam, istemci, zaman ve yanıt süresi.
HTTP durumu, hata kodu, deneme sayısı ve nihai durum.
Maskelenmiş hassas alanlar, güvenli header'lar ve imza doğrulama sonucu.
İzleme ve uyarılar
Yöntem, sağlayıcı, istemci ve neden kategorisine göre hata oranı.
Yavaş yanıtlar, HTTP 5xx hataları, geçersiz imzalar ve istek sıklığı sınırı olaylarındaki artış.
Tekrar sayısı, sonucu bilinmeyen işlemler ve kurtarma görevlerinin sayısı.
Eşikler, sorumlular ve escalation kurallarıyla uyarılar.
Test
Test ortamında neler test edilmeli
Test ortamı, önemli her hata kategorisini yeniden üretebilmeli ve istemci, tekrar deneme ve kontrol davranışlarının doğru çalıştığını doğrulamalıdır.
Girdi doğrulama hataları
Eksik alanlar, geçersiz türler, desteklenmeyen değerler, tutar hassasiyeti ve aynı anda birden fazla hata.
Erişim ve yetkiler
Geçersiz anahtar, süresi dolmuş token, hatalı imza, yetkisiz rol, engellenmiş IP ve yeniden kullanılmış nonce.
Yanıt yok ve sonuç bilinmiyor
Gönderim öncesinde, işlem kabul edildikten sonra veya nihai yanıt alınırken bağlantının kesilmesi.
İstek sıklığı sınırı
HTTP 429, önerilen bekleme süresi, eşzamanlı istekler ve limit sona erdikten sonra kurtarma.
Sağlayıcı hataları
Kullanılamama, bakım, geçersiz yanıt, gecikmiş bildirim ve çelişkili durum.
Tekrar deneme ve koruyucu durdurma
Deneme sayısını sınırlama, bekleme sürelerini artırma, istekleri geçici olarak durdurma, kontrollü kurtarma ve manuel escalation.
Lansman öncesi kontrol listesi
Canlı entegrasyon; hata yapısı, istemci davranışı, yinelenen işlemlere karşı koruma ve teşhis doğrulandıktan sonra başlatılır.
Tüm hatalar sabit bir neden kodu ve istek kimliği döndürür.
Hata ayrıntıları gizli bilgileri veya dahili uygulamayı açığa çıkarmaz.
Geçici ve kalıcı hata kategorileri dokümante edilmiştir.
Tekrar edilen kritik işlem aynı idempotency anahtarını kullanır.
Bilinmeyen sonuç, durum kontrol edilerek veya güvenilir bir bildirim alınarak ele alınır.
Günlükler, metrikler, uyarılar, kurtarma kuyruğu ve escalation kuralları yapılandırılmıştır.
API hatalarını standartlaştırmanız mı gerekiyor?
Mevcut HTTP yanıtlarınızı, hata kodlarınızı, tekrar kurallarınızı ve sorunlu senaryolarınızı bize iletin. APIACE birleşik hata modeli, güvenli kurtarma ve kontrol yaklaşımını tanımlamaya yardımcı olacaktır.