Hata kodları ve HTTP durumları
Her hata, HTTP durumunun yanında kararlı ve makine tarafından okunabilir bir kod döndürür. Mesaj metni üzerinden değil kod üzerinden dallanın: mesajlar insanlar için yazılmıştır ve yeniden ifade edilebilir, kodlar ise sözleşmenin parçasıdır.
Bayi API'sinin döndürebileceği 42 hata kodunun tamamı, neyin ters gittiğine göre gruplandırılmıştır. Her kayıt, geldiği HTTP durumunu ve sorunu çözen değişikliği belirtir.
Kimlik doğrulama (401)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| MISSING_API_KEY | 401 | API anahtarı gerekliAuthorization başlığı gönderilmedi ya da başlığın formatı hatalı. | Şu başlığı ekle: Authorization: Bearer <keyId>.<secret>action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_API_KEY | 401 | Geçersiz API anahtarıGönderilen API anahtarı sistemdeki aktif anahtarların hiçbiriyle eşleşmiyor. | Anahtar ID'sinin ve gizli anahtarın doğru olduğunu kontrol et. Gerekirse API Erişimi panelinden anahtarı yeniden oluştur.action: FIX_INPUT · retryable: false · retry_after: null |
Yetkilendirme (403)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| ACCOUNT_DISABLED | 403 | Hesap devre dışıArtık döndürülmüyor. Sipariş veremeyen hesaplar için ACCOUNT_FROZEN (HTTP 403) döner. | Bunun yerine ACCOUNT_FROZEN hatasını ele al.Artık döndürülmüyor, yerine ACCOUNT_FROZEN geldi |
| ACCOUNT_FROZEN | 403 | Hesap dondurulduHesabın geçici olarak donduruldu. Bunun nedeni genelde şüpheli bir hareket olur. | Hesabının dondurulmasını kaldırmak için destekle iletişime geç.action: CONTACT_SUPPORT · retryable: false · retry_after: null |
| IP_NOT_ALLOWED | 403 | IP adresi izin listesinde yokİstek, API anahtarının izin listesinde olmayan bir IP adresinden geldi. | Sunucunun IP adresini API Erişimi panelinden izin listesine ekle ya da IP kısıtlamalarını kaldır.action: FIX_INPUT · retryable: false · retry_after: null |
İstek doğrulama (400)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| MISSING_REQUIRED_FIELD | 400 | Zorunlu alan eksikİstek gövdesinde zorunlu bir alan eksik. Oyuncu gereksinimlerinde eksik alanın adı details.field içinde yer alır. | Endpoint dokümantasyonunu kontrol et. Oyuncu alanları için GET /catalog/category/:categoryId/requirements yanıtına da bak, ardından tüm zorunlu alanları gönder.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PARAMETER_FORMAT | 400 | Bir parametrenin formatı geçersizGereksinim alanlarından birinin formatı hatalı (örneğin sayısal bir alana metin girilmiş). Hangi alan olduğunu details.field gösterir. | Kategori gereksinimlerini tekrar incele ve alanı data_type değerinin ve doğrulama kurallarının beklediği formatta gönder.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PARAMETER_VALUE | 400 | Bir parametrenin değeri geçersizGereksinim alanlarından biri izin verilen değerlerin dışında: minimumun altında, maksimumun üstünde ya da select_options listesinde yok. İlgili alan details.field içinde belirtilir. | O alan için kategori gereksinimlerinin izin verdiği bir değer gönder.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PARAMETER_LENGTH | 400 | Bir parametrenin uzunluğu geçersizGereksinim alanlarından biri izin verilenden kısa ya da uzun. Alanın adı details.field içinde yazar. | Kategori gereksinimlerindeki min_length / max_length değerlerini kontrol et.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_UUID_FORMAT | 400 | Geçersiz UUID formatıorder_id geçerli bir UUID formatında değil. | Geçerli herhangi bir UUID biçimini kullanabilirsin (v1, v4, v7 vb.). Doğru yazım şöyle olmalı: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_QUANTITY | 400 | Geçersiz miktarMiktar pozitif bir tam sayı olmalı. | Miktarı >= 1 olan bir tam sayı olarak gönder.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_CATEGORY_ID | 400 | Geçersiz kategori ID'siGönderilen categoryId geçerli bir sayı değil. | Geçerli kategori ID'lerini bulmak için Katalog Gezgini'ni ya da GET /catalog/categories endpoint'ini kullan.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_BIG_CATEGORY_ID | 400 | Geçersiz ana kategori ID'sibigCategoryId değeri geçerli bir sayı değil. | Geçerli ana kategori ID'leri için Katalog Gezgini'ne ya da GET /catalog/big-categories endpoint'ine bak.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_ITEM_ID | 400 | Geçersiz ürün ID'siGönderilen ürün ID'si geçerli değil. | Geçerli ürün ID'lerini Katalog Gezgini'nden ya da GET /catalog/subcategories ile bulabilirsin.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_SUBCATEGORY | 400 | Geçersiz alt kategoriBu alt kategori ID'si mevcut değil. | sub_category_id değerini katalog endpoint'leriyle doğrula.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PRODUCT_CONFIG | 400 | Geçersiz ürün yapılandırmasıArtık döndürülmüyor. Eksik bir gereksinim alanında MISSING_REQUIRED_FIELD, şu an satılamayan bir üründe ise PRODUCT_UNAVAILABLE döner. | Bunun yerine MISSING_REQUIRED_FIELD ve PRODUCT_UNAVAILABLE kodlarını ele al.Artık döndürülmüyor, yerine MISSING_REQUIRED_FIELD geldi |
| INVALID_PAGINATION | 400 | Geçersiz sayfalama parametreleripage ya da limit değeri izin verilen aralığın dışında. | page için >= 1, limit için 1 ile 100 arasında bir değer kullan.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_DATE_FORMAT | 400 | Geçersiz tarih formatıcreated_after veya created_before parametresi geçerli bir ISO 8601 tarihi değil. | ISO 8601 formatını kullan: 2024-01-01T00:00:00Z.action: FIX_INPUT · retryable: false · retry_after: null |
Oyuncu doğrulama (400 / 429 / 503)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| PLAYER_NOT_FOUND | 400 | Oyuncu bulunamadıOyun, bu oyuncu ID'sinin mevcut olmadığını doğruladı. Bu kod yalnızca kesin bir yanıtta döner. ID kontrol edilemediğinde onun yerine PLAYER_CHECK_UNAVAILABLE alırsın. | Oyuncu ID'sinin doğru olduğundan emin ol. Oyunun zone_id isteyip istemediğine de bak.action: FIX_INPUT · retryable: false · retry_after: null |
| PLAYER_CHECK_UNAVAILABLE | 503 | Bu oyunun oyuncu ID'leri şu an doğrulanamıyorBu oyun için oyuncu ID kontrolü şu anda yapılamıyor. Oyuncu ID'si REDDEDİLMEDİ. | retry_after saniye sonra aynı isteği tekrar gönder. Müşterine ID'nin yanlış olduğunu söyleme.action: RETRY_LATER · retryable: true · retry_after: 60 |
| PLAYER_BUSY | 429 | Bu oyuncu ID'si zaten kontrol ediliyorAynı oyuncu ID'si için gönderilen başka bir istek hâlâ kontrol ediliyor. | İsteği retry_after saniye geçtikten sonra yeniden gönder.action: RETRY_SOON · retryable: true · retry_after: 5 |
| PLAYER_VALIDATION_FAILED | 400 | Oyuncu doğrulaması başarısızBu kod artık dönmüyor. Şu an kontrol edilemeyen bir oyuncu ID'si için PLAYER_CHECK_UNAVAILABLE (HTTP 503) döner. | Artık PLAYER_CHECK_UNAVAILABLE kodunu ele al.Artık döndürülmüyor, yerine PLAYER_CHECK_UNAVAILABLE geldi |
| REGION_MISMATCH | 400 | Bu oyuncunun bölgesi bu ürünü alamıyorOyuncu, bu ürünün teslim edilemediği bir bölgede. Hata yanıtında player_region ve player_name bilgileri de gelir. | Oyuncunun bölgesine uygun ürünü seç.action: CHOOSE_OTHER · retryable: false · retry_after: null |
İş kuralları (400 / 409)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| INSUFFICIENT_BALANCE | 400 | Cüzdan bakiyesi yetersizCüzdanında bu siparişi tamamlamaya yetecek bakiye yok. | Siparişi vermeden önce Yükleme sayfasından cüzdanına bakiye yükle.action: TOP_UP · retryable: false · retry_after: null |
| OUT_OF_STOCK | 400 | Ürün stokta yokİstediğin ürün şu anda stokta bulunmuyor. | Daha sonra tekrar dene ya da başka bir ürün seç.action: RETRY_LATER · retryable: true · retry_after: null |
| INSUFFICIENT_STOCK | 400 | Stokta istenenden daha az adet varStokta, siparişinde istediğinden daha az adet var. OUT_OF_STOCK'tan farkı, bu hatada yapabileceğin bir şey olması: error.max_quantity şu anda sipariş verilebilecek adet sayısını gösterir. Hiçbir ücret kesilmedi. | Siparişi error.max_quantity veya daha düşük bir adetle tekrar gönder.action: FIX_INPUT · retryable: false · retry_after: null |
| PRODUCT_UNAVAILABLE | 409 | Bu ürün geçici olarak satışta değilÜrün mevcut ama şu anda satılamıyor. | Daha sonra tekrar dene ya da başka bir ürün seç.action: RETRY_LATER · retryable: true · retry_after: null |
| PRICING_UPDATING | 409 | Ürün fiyatı güncelleniyorBu ürünün fiyatı yenileniyor. | retry_after saniye sonra aynı isteği tekrar gönder, ardından fiyatı yeniden kontrol et.action: RETRY_SOON · retryable: true · retry_after: 30 |
| OFFER_NOT_FOUND | 400 | Bu teklif bu oyuncu hesabı için geçerli değilTek seferlik bir teklif (örneğin ilk yükleme bonusu) bu oyuncu hesabı için geçerli değil. Daha önce kullanılmış olabilir. | Bu oyuncu için başka bir ürün seç.action: CHOOSE_OTHER · retryable: false · retry_after: null |
| DUPLICATE_ORDER | 409 | Yinelenen sipariş ID'siBu UUID ile oluşturulmuş bir sipariş zaten var. Bu bir idempotency korumasıdır. | Yeni bir sipariş için yeni bir UUID oluştur. Bu hatayı bir yeniden denemede alıyorsan ilk deneme başarılı olmuş demektir: başka bir sipariş oluşturmak yerine o siparişi GET /orders/{orderId} ile oku.action: CHECK_ORDER · retryable: false · retry_after: null |
| PRICE_INCREASED | 400 | Fiyat beklenenin üzerine çıktıGüncel birim fiyat, gönderdiğin expected_unit_price değerinden yüksek. | En güncel fiyatı GET /catalog/subcategory/:id/price ile çek ve expected_unit_price değerini güncelle.action: FIX_INPUT · retryable: false · retry_after: null |
| SUBCATEGORY_DISABLED | 400 | Alt kategori devre dışıArtık döndürülmüyor. Şu anda satılamayan bir ürün PRODUCT_UNAVAILABLE (HTTP 409) yanıtını verir. | Bunun yerine PRODUCT_UNAVAILABLE'ı işle.Artık döndürülmüyor, yerine PRODUCT_UNAVAILABLE geldi |
Bulunamadı (404)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| ORDER_NOT_FOUND | 404 | Sipariş bulunamadıVerilen sipariş ID'sine ait bir sipariş yok. | Sipariş ID'sinin doğru olduğunu kontrol et.action: FIX_INPUT · retryable: false · retry_after: null |
| ITEM_NOT_FOUND | 404 | Öğe bulunamadıİstenen katalog öğesi mevcut değil. | Geçerli öğe ID'lerini bulmak için katalog endpoint'lerini kullan.action: FIX_INPUT · retryable: false · retry_after: null |
| NO_REQUIREMENTS_FOUND | 404 | Bu kategori için gereksinim bulunamadıBu kategori için şu anda döndürülecek bir oyuncu gereksinimi yok. | Biraz sonra yeniden dene veya başka bir kategori seç.action: RETRY_LATER · retryable: true · retry_after: null |
| ITEM_NOT_AVAILABLE | 404 | Öğe satışta değilArtık döndürülmüyor. Mevcut olup şu anda satılamayan bir öğe PRODUCT_UNAVAILABLE (HTTP 409) yanıtını verir. | Bunun yerine PRODUCT_UNAVAILABLE'ı işle.Artık döndürülmüyor, yerine PRODUCT_UNAVAILABLE geldi |
Toplu istek doğrulama (400)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| INVALID_ORDER_IDS_FORMAT | 400 | Geçersiz order_ids formatıorder_ids alanı string'lerden oluşan bir dizi olmalı. | order_ids'i şu şekilde gönder: { "order_ids": ["uuid1", "uuid2"] }.action: FIX_INPUT · retryable: false · retry_after: null |
| EMPTY_ORDER_IDS | 400 | Boş order_ids dizisiorder_ids dizisi boş olamaz. | Diziye en az bir sipariş ID'si ekle.action: FIX_INPUT · retryable: false · retry_after: null |
| TOO_MANY_ORDER_IDS | 400 | Çok fazla sipariş ID'siTek seferde en fazla 50 sipariş ID'si sorgulanabilir. | İsteğini en fazla 50 ID içeren parçalara böl.action: FIX_INPUT · retryable: false · retry_after: null |
Hız sınırı (429)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| RATE_LIMIT_EXCEEDED | 429 | İstek limiti aşıldıBu endpoint için limiti aştın. Dakikalık kotalar (catalog, orders, account) her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını gönderir; details de limit, remaining (0), retry_after ve window_seconds değerlerini tekrarlar. POST /player/validate ise günlük oyuncu kontrol kotana göre ölçülür: X-RateLimit başlığı göndermez ve 429 yanıtında error içinde limit, current, remaining, reset_at ve reset_in_seconds yer alır. Her iki durumda da beklemen gereken saniye error.retry_after alanında ve Retry-After başlığında bulunur. | Yeniden denemeden önce retry_after değerindeki ya da Retry-After başlığındaki saniye kadar bekle. Dakikalık endpoint'lerde limite hiç takılmamak için X-RateLimit-Remaining değerini takip et.action: RETRY_LATER · retryable: true · retry_after: sıfırlanmaya kalan saniye |
Sunucu tarafı (5xx)
| Kod | HTTP | Ne anlama gelir | Nasıl düzeltilir |
|---|---|---|---|
| INTERNAL_ERROR | 500 | Dahili sunucu hatasıSunucuda beklenmeyen bir hata oluştu. | İsteği retry_after saniye sonra yeniden gönder. POST /orders/create için aynı order_id değerini kullan, böylece sipariş asla iki kez oluşmaz. Sorun devam ederse destekle iletişime geç.action: RETRY_LATER · retryable: true · retry_after: 30 |
| SERVICE_UNAVAILABLE | 503 | Hizmet geçici olarak kullanılamıyorArtık döndürülmüyor. Sunucu tarafındaki bir hata INTERNAL_ERROR (HTTP 500) yanıtını verir; tek 503 yanıtı PLAYER_CHECK_UNAVAILABLE'dır ve bir oyuncu ID'si şu anda kontrol edilemediğinde döner. | Bunun yerine INTERNAL_ERROR ve PLAYER_CHECK_UNAVAILABLE'ı işle.Artık döndürülmüyor, yerine INTERNAL_ERROR geldi |
Platformda yeni misiniz? bayiler için oyun yükleme API'sine genel bakış ile başlayın veya SHOP2TOPUP bayi programına genel bakış sayfasından iş ortağı hesabının nasıl çalıştığını okuyun.