Hata referansı

Bu sayfa, Open Play’in döndürdüğü her hata türünü, durum kodunu ve gövde biçimini listeler. Hata yönetimi kodu yazarken önce hangi uç ailesinin (çekirdek REST mi, eklenti mi) çağrıldığına bakın: iki ailenin hata gövdesi farklıdır.

Uyarı

Çekirdek REST uçlarının çoğu düz metin (text/plain) hata döner, JSON değil. Yalnız bu sayfada “JSON” diye işaretlenen birkaç hata JSON zarfı taşır. Hata metnini ayrıştırmayın; durum koduna ve (varsa) JSON code alanına göre karar verin. Düz metin mesajlar sürümler arasında değişebilir.

Hata aileleri

Aile	Hangi uçlar	Gövde
Çekirdek REST	`/v1/characters…`, `/v1/wallets…`, `/v1/store…`, `/v1/auth/…` vb. (uç noktalar)	Düz metin; birkaç hata JSON `{code, message[, module]}`
Eklenti	`/v1/plugins/…`	Her zaman JSON `{code, message, retryable, requestId[, reason, module]}` + `x-request-id` başlığı
Realtime	`/v1/realtime/ws`	`Error` çerçevesi: `{type, requestId?, code, retryable}` (protokol)
Sohbet soketi	`/v1/chat/ws`	`{"type":"error","code":"…"}` (realtime genel bakış)

Çekirdek REST: durum tablosu

Durum	Gövde (düz metin, aksi belirtilmedikçe)	Ne zaman	Yeniden dene?
`400`	Hatanın açıklaması	Eksik ya da bozuk başlık, geçersiz alan, bilinmeyen komut türü, `If-Match` biçimi	Hayır; isteği düzeltin
`401`	`unauthorized`	API anahtarı ya da oyuncu oturumu yok, geçersiz, süresi dolmuş; `x-crx-env` yok ya da bozuk; yasaklı hesap (ayrım yapılmaz)	Hayır; kimliği yenileyin
`403`	`permission denied`	Anahtar türü yetmiyor (ör. istemci anahtarıyla sunucu ucu), CSRF ya da Origin reddi	Hayır
`403`	JSON `{"code":"account_banned","message":"account banned"}`	Giriş uçlarında, sahiplik kanıtlandıktan sonra yasaklı hesap	Hayır; döngü kurmayın
`404`	`not found`	Kaynak yok ya da silinmiş	Hayır
`404`	JSON `{"code":"module_disabled","message":"module disabled","module":"store"}`	Ürün modülü ortamda kapalı	Hayır; modülü açın (modüller)
`409`	`version conflict: expected 3, actual 5`	`If-Match` sürümü gerçekle uyuşmuyor	Durumu yeniden okuyup yeni sürümle tekrar edin
`409`	`already exists: <kaynak>`	Aynı kimlik/anahtarla kaynak zaten var	Hayır
`409`	`idempotent request in progress`	Aynı `Idempotency-Key` ile ilk istek hâlâ işleniyor	Evet, kısa süre sonra aynı anahtarla
`410`	`idempotent request result expired`	Anahtarın kayıt süresi (24 saat) doldu	Yeni anahtarla, durumu önce okuyarak
`413`	Gövdesiz	İstek gövdesi 2 MiB sınırını aştı (görsel yükleme ucu kendi sınırına tabidir)	Hayır
`422`	`idempotency mismatch`	Aynı anahtar, farklı içerik	Hayır; anahtarı yeniden kullanmayın
`422`	`unprocessable: <neden>`	İş kuralı reddi (yetersiz bakiye, stok, limit…)	Hayır; durumu değiştirmeden tekrar etmeyin
`422`	`rejected: <kod>`	Eklenti iş kuralı reddi (çekirdek rotalar üzerinden)	Hayır
`429`	`rate limited` ya da `rule budget exceeded: <kural>`	Oran sınırı ya da kural bütçesi	Evet, bekleyerek (hız sınırları); `Retry-After` yoktur
`500`	`internal error`	Beklenmeyen sunucu hatası; ayrıntı sızdırılmaz	Evet, sınırlı
`503`	`tenant unavailable`; başlık `Retry-After: 30`	Ortamın yerleşimi taşınıyor ya da geçici kullanılamıyor	Evet, `Retry-After` sonra

Notlar:

Gövde ayrıştırma hatalarında çıkarıcıya göre 415 (yanlış Content-Type) ya da 422 (şemaya uymayan JSON) da görülebilir. Karar için yalnız durum koduna güvenin.
401 ve 403 farkı: kimlik yok ya da çözümlenemiyorsa 401; kimlik geçerli ama bu işleme yetmiyorsa 403. Oyuncu bilet ucunda tüm kimlik hataları 403 döner (realtime protokolü).
İstemci anahtarıyla bir sunucu ucunu çağırırsanız 403 permission denied alırsınız; anahtarın bilinmemesi ise 401’dir.

Satın alma (`POST /v1/player/store/listings/{listing_id}/buy`) hata kodları

Oyuncu satın alma ucu, ret nedenini JSON code ile söyler: {"code":"out_of_stock","message":"…"} (message ayrıntı metnidir, kararınızı code’a göre verin).

`code`	Durum	Anlam
`not_visible`	404	İlan yok ya da bu oyuncuya görünmüyor
`listing_changed`	409	İlanın sürümü (`expected_version`) değişti; kataloğu yenileyip yeniden gösterin
`out_of_stock`	422	Stok bitti
`limit_reached`	422	Oyuncu başına satın alma sınırı doldu
`insufficient_funds`	422	Bakiye yetmiyor
`inventory_full`	422	Envanter dolu

Bunun dışındaki hatalar (400 başlık/gövde, 401, 403 Origin ya da CSRF, idempotency uyuşmazlığı 422) yukarıdaki genel tablodaki gibidir. IAP ilanı bu uçtan alınamaz (422). Ayrıntı: mağaza rehberi.

Eklenti uçları

Eklenti uçları JSON zarf döner; requestId değerini destek taleplerinde iletin (aynı değer x-request-id başlığında da bulunur).

{"code":"unprocessable","message":"plugin command rejected","retryable":false,"requestId":"0192a3b4-0000-7000-8000-0000000000d1","reason":"street_reset_too_early"}

`code`	Durum	`retryable`	Not
`unauthorized`	401	hayır	Oturum/anahtar yok ya da geçersiz; istemci anahtarı
`forbidden`	403	hayır	CSRF/Origin reddi; eklenti etkin değil; sürüm yetkisi uyuşmuyor; yasaklı hesap (`message: account banned`)
`module_disabled`	404	hayır	`module` alanı kapalı modülü söyler
`not_found`	404	hayır	Bilinmeyen eklenti ya da mesaj türü
`invalid_argument`	400	hayır	Bozuk/eksik başlık, bilinmeyen şema sürümü, şemaya uymayan yük
`conflict`	409	hayır	`If-Match` sürümü uyuşmuyor
`idempotency_in_flight`	409	evet	Aynı anahtarlı istek işleniyor
`idempotency_mismatch`	422	hayır	Aynı anahtar, farklı gövde
`unprocessable`	422	hayır	İş kuralı reddi; `reason` eklentiye özgü makine kodudur
`idempotency_expired`	410	hayır	Kayıt süresi doldu
`rate_limited`	429	evet	`Retry-After: 60`
`tenant_unavailable`	503	evet	`Retry-After: 30`
`internal`	500	evet

Ayrıntı ve örnekler: eklentileri çağırma.

Not

Eklenti ucunda yasaklı hesap, çekirdek kimlik uçlarının aksine account_banned koduyla gelmez: 403, forbidden ve message: "account banned" döner. Bu ayrıma yalnız bir kullanıcı arayüzü mesajı için ihtiyaç duyarsınız; yeniden deneme döngüsü kurmayın.

Çekirdek ile eklenti arasındaki farklar

	Çekirdek REST	Eklenti
Gövde	Düz metin (birkaç JSON istisna)	Daima JSON
Makine kodu	Yalnız JSON olan hatalarda	Her hatada `code`
`retryable`	Yok; durum koduna göre karar verin	Var
Yeniden deneme süresi	Yalnız `503` (30 sn)	`429` (60 sn) ve `503` (30 sn)
Yasaklı hesap	`403` `account_banned` (giriş uçlarında)	`403` `forbidden`
`x-request-id`	Yok	Var

Hata işleme önerisi

Önce durum koduna bakın; 401 oturumu yenileyin ya da yeniden giriş yaptırın, 403 yetki ya da yapılandırma sorunudur (anahtar türü, CSRF, modül, eklenti durumu).
404 için gövdeyi okuyun: JSON ve module_disabled ise modül kapalıdır, yoksa kaynak yoktur.
409’u iki ayrı biçimde ele alın: sürüm çakışması (durumu yeniden okuyun) ile idempotency “işleniyor” (bekleyip aynı anahtarla tekrar edin).
429 ve 503’te üstel geri çekilme kullanın; Retry-After varsa onu bekleyin (idempotency ve eşzamanlılık sayfasındaki örnek).
422 iş kuralı reddidir; aynı isteği olduğu gibi tekrarlamak sonuç değiştirmez.
Sunucu hata ayrıntısı sızdırmaz; sorun bildirirken durum kodunu, istek zamanını ve (eklenti uçlarında) requestId’yi iletin (sorun giderme).

Keyboard shortcuts

Open Play geliştirici dokümanı