Hata Kodları

Yanıt zarfı, error_code listesi ve sık karşılaşılan durumlar.

Yanıt zarfı#

API'nin tüm yanıtları aynı zarfı kullanır — başarılı olanlar da dahil:

JSON

{
  "status": true,
  "data": { "session_id": "01J8ZQ..." },
  "error_code": 0,
  "error_message": null
}

Hata durumunda:

JSON

{
  "status": false,
  "data": [],
  "error_code": 2155,
  "error_message": "Tanınmayan scope değeri"
}

Alan	Açıklama
`status`	`true` başarı, `false` hata.
`data`	Başarılı yanıtın içeriği; hatada boş dizi (`[]`).
`error_code`	Sayısal hata kodu. Başarıda `0`.
`error_message`	İnsan için açıklama. Başarıda `null`.

Genel kodlar#

Kod	Anlamı
`0`	Hata yok.
`1000`	Sunucu tarafında beklenmeyen hata.
`1001`	İstek gövdesi geçersiz.
`1002`	İstek sınırı aşıldı.

Doğrulama oturumu kodları#

Kod	Anlamı	Ne yapmalı
`2151`	Publishable anahtar bu uçta kullanılamaz	Gizli anahtar (`sk_`) kullanın.
`2152`	Oturum bulunamadı	`session_id` doğru mu, size mi ait?
`2153`	Oturumun süresi doldu	Yeni oturum açın.
`2154`	Oturum zaten sonuçlanmış	Sonucu okuyun; tekrar karar verilemez.
`2155`	Geçersiz scope	Scope sözlüğüne bakın.

Kimlik doğrulama kodları#

Kod	Anlamı
`2101`	Yetkisiz — anahtar yok, geçersiz veya iptal edilmiş.
`2102`	İmzanın süresi dolmuş.
`2103`	Cihaz aktif değil.
`2104`	İmza tekrar kullanılmış.

2102–2104 mobil uygulamanın cihaz imzasına aittir; entegratörler genellikle yalnızca 2101 ile karşılaşır.

Yükleme kodları#

Kod	Anlamı
`2201`	Desteklenmeyen dosya türü.
`2202`	Dosya çok büyük.
`2203`	Görsel kare değil.

HTTP durum kodları#

error_code ile birlikte anlamlı bir HTTP durumu da döner:

Durum	Genel anlamı
`400`	İstek hatalı.
`401`	Kimlik doğrulanamadı.
`403`	Anahtar türü yetersiz.
`404`	Kaynak yok.
`422`	Doğrulama hatası.
`429`	İstek sınırı aşıldı.
`5xx`	Bizim tarafımızda hata.

Sık karşılaşılanlar#

2151 — publishable anahtarla sonuç okumaya çalışmak#

En sık yapılan hata budur. pk_ oturum açabilir ama sonuç okuyamaz. Bunun 2101 yerine ayrı bir kod olması bilinçlidir: sorun anahtarınızın geçersiz olması değil, yanlış türde olmasıdır. Sonuç okuyan kodunuz sunucunuzda çalışmalı ve sk_ kullanmalıdır.

2155 — tanınmayan scope#

Scope sözlüğünde olmayan bir değer gönderdiniz. Sessizce atlamıyoruz, çünkü atlasaydık hiç gelmeyecek bir alanı bekliyor olurdunuz.

2152 — oturum bulunamadı#

Üç olasılık: session_id yanlış, oturum başka bir organizasyona ait, ya da silinmiş. Başka bir organizasyonun oturumu da 2152 döner — ayrı bir kod dönseydi, o oturumun var olduğunu doğrulamış olurduk.

Yeniden deneme#

1002 (429) ve 5xx yeniden denenebilir. Sabit aralıkla değil, artan bekleyişle deneyin (1s, 2s, 4s…) ve bir üst sınır koyun.

Diğer 4xx hatalarını yeniden denemeyin — istek aynı kaldığı sürece sonuç da aynı kalır.