Hatalar

Partner API'nin döndürdüğü her hata; sabit bir sayısal code, ait olduğu domain ve okunabilir bir message taşıyan bir JSON nesnesidir. Dallanmayı domain + code çifti üzerinden yapın. message alanını ayrıştırmayın: loglar içindir ve zamanla ayrıntı kazanabilir.

{
  "code": 10016,
  "domain": 100,
  "message": "invalid id format"
}

Alan	Tip	Açıklama
code	number	Hata kimliği. 10000–10018 kodları ortak domain'e (100) aittir; diğer her alanın (token, düğüm, ücret, KYC, OTC, …) kendi domain'i ve kodları vardır ve ilgili endpoint sayfasında listelenir. Aynı numara birden fazla domain'de görülebilir (örneğin 10001 birçoğunda "bulunamadı" anlamına gelir); bu yüzden bir hatayı domain + code çifti ile tanımlayın.
domain	number	Hatanın geldiği alan. 100, tüm endpoint'lerin paylaştığı ortak domain'dir.
message	string	Kısa İngilizce açıklama.
details	array	Yalnızca doğrulama hatalarında bulunur, aşağıya bakın.

Doğrulama hataları

Doğrulamadan geçemeyen bir istek (eksik zorunlu alan, aralık dışı değer, hatalı biçimli tutar) HTTP 400 ve 10015 koduyla yanıtlanır. details, düzeltilmesi gereken her alanı isteğin gönderdiği adla (JSON anahtarı, query ya da path parametresi) listeler:

{
  "code": 10015,
  "domain": 100,
  "message": "invalid request payload: wallet_id: Validation failed on the 'required' tag",
  "details": [
    { "field": "wallet_id", "message": "Validation failed on the 'required' tag" }
  ]
}

Bazı handler'lar yalnızca kendilerinin kontrol edebildiği bir değeri (kayıtlı veriye ihtiyaç duyan) aynı biçimle reddeder. Birkaç domain hatası 10015 numarasını kendi domain'inde details olmadan kullanır (örneğin domain 1, "wallet does not belong to this user on this network"); bu yüzden domain önemlidir. Tutar ve yüzde kuralları Tutarlar ve Yüzdeler sayfasındadır.

HTTP durum kodları

Durum	Ne zaman
400	İstek reddedildi: doğrulama (10015), hatalı biçimli id (10016) ya da bir domain kuralı (endpoint'in kendi kodları). Çoğu "bulunamadı" hatası dahil domain hatalarının çoğu 400 döner; her endpoint sayfası kendi kodlarını ve durumlarını listeler.
401	Kimlik doğrulama başarısız: eksik, hatalı ya da süresi dolmuş access token, bilinmeyen client, client'ın izin listesi dışındaki bir IP veya client'a ait olmayan bir sertifika. Gövde genel {"code": -1, "domain": 100, "message": "unexpected error"} yanıtıdır; belirleyici olan durum kodudur.
403	Token geçerli ancak endpoint'in istediği izne sahip değil (gateway'de reddedilir).
404	Route yok (gateway'de reddedilir). Birkaç endpoint eksik bir kayıt için de 404 döner; sayfaları bunu belirtir.
409	İşlem, kaydın mevcut durumuyla çakışıyor (örneğin süren bir deploy); endpoint bunu belirtir.
429	Hız sınırı (10011) ya da aylık kullanım sınırı (10012) aşıldı. Bkz. Kullanım / Skor.
500	Beklenmeyen sunucu hatası (10000). İdempotent okumalar tekrar denenebilir; yazma işlemlerinde tekrar denemeden önce kaynağı ya da işlemini kontrol edin.

Ortak kodlar

Kod	Durum	Mesaj	Anlamı
-1	401 / 404 / 405	unexpected error	Çatı (framework) seviyesinde ret: kimlik doğrulama başarısız, route ya da metot yok.
10000	500 (bazen 400)	unexpected error	Beklenmeyen bir hata, genellikle veri deposu ya da iletim hatası. Asıl neden sunucu tarafında kalır.
10001	401	token expired	Access token'ın süresi doldu. refresh_token grant ile yenileyin.
10011	429	rate limit exceeded	Saniye / dakika / saat sınırına ulaşıldı. Retry-After kadar bekleyin.
10012	429	monthly usage limit exceeded	Client'ın aylık skor kotası doldu.
10013	500	missing client id	Token bir client id taşımıyor. Yeni token alın.
10015	400	invalid request payload	Doğrulama hatası, yukarıya bakın.
10016	400	invalid id format	Path ya da gövdedeki bir id, geçerli 24 karakterlik hex id değil.
10017	—	transaction failed	Custody ya da zincirin başarısız bildirdiği bir işleme yazılır; işlemin error alanından okunur.
10018	—	transaction is already settled	Zaten done ya da error durumundaki bir işleme ikinci bir durum güncellemesi ulaştı.

Asenkron işlemler

Zincir üzerindeki işlemler (deploy, mint, burn, kira, OTC kabul, para çekme, …) 200 ile kabul edilir ve daha sonra sonuçlanır. Kabulden sonraki bir başarısızlık HTTP hatasına dönüşmez: işlemin kaydı 4 (error) durumunda biter ve nedeni error alanında yer alır; başarı 3 (done) durumudur. 1 (started), 2 (in progress) ve 5 (pending receipt) ara durumlardır. Her asenkron endpoint, izlenecek işlem okumasını belirtir.