Javob kodlari va xatolar

HTTP kodlari

Kod	Qachon qaytariladi	Nima qilish kerak
200	muvaffaqiyat	—
201	obyekt yaratildi	—
400	kirish ma’lumotlari validatsiyasi xatosi	so’rovni tuzatish, takrorlamaslik
401	token mavjud emas, muddati tugagan yoki yaroqsiz	tokenlar juftligini yangilash va bir marta takrorlash
403	marshrut uchun ruxsatlar yo’q, kompaniya bloklangan yoki kalit faollashtirilmagan	ruxsatlar berish; kompaniya va kalit holatini tekshirish
404	marshrut yoki obyekt topilmadi	yo’l va identifikatorni tekshirish
408	asinxron javobni kutish vaqti tugadi (600 s; hisobotlarni Excel’ga eksport qilishda — 100 s)	obyekt holatini alohida so’rov bilan tekshirish
422	biznes-validatsiya xatosi	ma’lumotlarni tuzatish
429	og’ir marshrutda cheklagich ishga tushdi	eksponensial kechikish bilan takrorlash
500	ichki xato	1–2 marta takrorlang, keyin correlation_id bilan qo’llab-quvvatlash xizmatiga murojaat qiling

Tana formatlari

Klassik konvert — aksariyat metodlar va kirishni tekshirish shunday javob qaytaradi

{ "code": 401, "message": "token expired", "error": "token has been expired", "data": null }

Xato obyekti

{ "error": { "code": "BAD_REQUEST", "message": "shop_id is required" } }

Asinxron javob konverti

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "company_id": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "status_code": 400,
  "error": { "code": "BAD_REQUEST", "message": "..." },
  "correlation_id": "00000000-0000-0000-0000-000000000000"
}

Bu holda yakuniy HTTP-kod status_code maydonidan, yaratilgan yoki o’zgartirilgan obyekt ID’si esa id dan olinadi.

Konvertning bo’sh maydonlari javobga kiritilmaydi (omitempty); xato konvertida data odatda bo’lmaydi.

Taym-aut tanasi — xuddi shu kanal, lekin qisqaroq: unda status_code maydoni yo’q.

{ "correlation_id": "...", "error": { "code": "TIMEOUT", "message": "Timeout waiting for response" } }

error.code birinchi bo’lib tekshiriladi.

Kalit kodlar semantikasi

401 — token

Sababi message + error juftligiga qarab farq qiladi:

message	error	Nima bo’ldi
token error	JWT tahlili matni	token kesilgan, buzilgan yoki noto’g’ri kalit bilan imzolangan
token expired	token has been expired	muddati tugagan — yangilash talab etiladi
unauthorized	refresh token used as access	Authorization ga refresh-token kiritilgan
unauthorized	session not found / session revoked	sessiya yopilgan yoki bekor qilingan — yangi login kerak
unauthorized	mismatch platform-id with token info	platform-id token berilganiga mos emas
unauthorized	user is not active / user has been expired	kalit o’chirilgan yoki uning muddati o’tgan

Tokenlar juftligi POST /v2/auth/refresh orqali yangilanadi (platform-id sarlavhasi kerak). Agar refresh-tokenning ham muddati o’tgan bo’lsa, yangi token POST /v1/auth/login orqali chiqariladi. Yangilash jarayonidagi xatoliklar sababi tavsiflangan holda 400 kodi bilan qaytadi.

403 — ruxsatlar

Metod mavjud, token yaroqli, biroq «metod + marshrut shabloni» juftligi kalit uchun ruxsat etilgan ro’yxatga kirmaydi.

Yana ikkita holatda xuddi shu kod qaytadi: kompaniya bloklangan ("error": "company is blocked") va kalit faollashtirilmagan ("error": "user hasn't been activated").

429 — chastota

Perimetrdagi umumiy limit — bitta IP dan soniyasiga 2 ta so’rov. Undan tashqari alohida og’ir marshrutlarda o’z cheklovchilari bor: qidiruv marshrutlari va hisobotlarni Excel’ga eksport qilish (soniyasiga 5 ta so’rov). Bu hisoblagichlar platformaning barcha mijozlari uchun umumiy.

408 — asinxron javob taym-auti

Asinxron operatsiya natijasi 600 soniya ichida kelmaganda yuzaga keladi; hisobotlarni Excel’ga eksport qilishda kutish qisqaroq — 100 soniya. Bunda operatsiya bajarilgan bo’lishi ham mumkin — yozishni ko’r-ko’rona takrorlash mumkin emas.

Biznes-kodlar

Satrli

error / error.code maydonida satrli kodlar uchraydi: BAD_REQUEST, TIMEOUT, TOO_MANY_REQUESTS, rate_limited, tokenni yangilash javoblarida esa RFC 6749 §5.2 kodlari beriladi: invalid_request, invalid_grant, unauthorized_client, server_error.

Raqamli — sotuvlarda

Sotuv metodlari 400 qaytaradi, aniq sababi esa data.error_code dagi raqam orqali ifodalanadi:

{
  "status_code": 400,
  "error": { "code": "", "message": "status: 400 - errors: Bad request - causes: ..." },
  "data": {
    "error_code": 20084,
    "message": "payment is possible only for calculated order",
    "data": null
  }
}

Bu yerdagi error.code — bo’sh satr.

Onlayn do’konni integratsiya qilishda eng ko’p uchraydigan kodlar:

Kod	Ma’nosi	Nima qilish kerak
20084	to’lovni faqat qayta hisoblangan savat uchun amalga oshirish mumkin	pozitsiyalar noto’g’ri metod bilan qo’shilgan — POST /v2/order-product/:order_id kerak
20082	yopiq smenada to’lov qilish	sotuv do’konida smenani ochish
20010	foydalanuvchida joriy kassa yo’q	smenani ochish; kassani tizim tanlaydi, uni tanada uzatishdan foyda yo’q
20009	kassa do’koni va sotuv do’koni har xil	sotuv boshqa do’konda yaratilgan
20015	sotuvda pozitsiyalar yo’q	to’lovdan oldin mahsulotlarni qo’shish
20016	mahsulot yetarli emas	sotuv do’konidagi qoldiqni tekshirish
20017	qoralama o’chirildi	yangi yaratish
20020	noto’g’ri to’lov summasi	to’lovlar summasi chek summasiga mos kelishi kerak
20033	smena topilmadi	smenani ochish
20036	mahsulot topilmadi	tekshirish product_id
20037	mahsulot arxivda	arxivdagi mahsulotni sotish mumkin emas
20063	sotuv OFDga yuborilmagan	skip_ofd bayrog’i bilan olib tashlanadi
20085	sotuvchida do’konga kirish ruxsati yo’q	tekshirish seller_id

Asosiy mo’ljal — HTTP-kod; raqamli va satrli kodlar aniq diagnostika va loglar uchun xizmat qiladi.

Xato tanasini tahlil qilish

def parse_error(resp):
    try:
        body = resp.json()
    except ValueError:
        return {"code": resp.status_code, "message": resp.text[:300]}
    err = body.get("error")
    if isinstance(err, dict):
        return {"code": body.get("status_code", resp.status_code),
                "message": err.get("message") or err.get("code")}
    return {"code": body.get("code", resp.status_code),
            "message": body.get("message") or (err if isinstance(err, str) else "unknown")}

correlation_id javobdan logga yoziladi — u orqali qo’llab-quvvatlash xizmati trassirovkadan so’rovni topadi.