Format#

Xato javoblari Content-Type: application/problem+json bilan qaytadi (RFC 9457):

Maydon	Tavsif
`type`	Hujjatdagi xato sahifasiga URI (`…/docs/errors#<code>`)
`title`	Qisqa, odam o'qiy oladigan sarlavha
`status`	HTTP status kodi
`detail`	Aniq holat bo'yicha tushuntirish (o'zgarishi mumkin — kodda solishtirmang)
`code`	Barqaror mashina kodi — mantiqni shunga qarab quring
`request_id`	So'rov ID si (`X-Request-Id` bilan bir xil)
`errors`	Faqat `validation_error`: `[{field, message}]`

422 validatsiya

{
  "type": "https://api.milliysavdo.uz/docs/errors#validation_error",
  "title": "Maydonlar tekshiruvdan o'tmadi",
  "status": 422,
  "detail": "So'rov maydonlari noto'g'ri",
  "code": "validation_error",
  "errors": [
    {
      "field": "country_id",
      "message": "Input should be greater than or equal to 1",
      "type": "greater_than_equal"
    },
    {
      "field": "service_code",
      "message": "Field required",
      "type": "missing"
    }
  ],
  "request_id": "req_a9ce2c4d85f7162a99297d2c"
}

404

{
  "type": "https://api.milliysavdo.uz/docs/errors#not_found",
  "title": "Topilmadi",
  "status": 404,
  "detail": "Buyurtma topilmadi",
  "code": "not_found",
  "request_id": "req_6e73e3f1328ea25dd4272531"
}

Xatolarni qayta ishlash#

Python

resp = requests.post(f"{API}/orders", json=payload, headers=headers, timeout=30)
if resp.ok:
    order = resp.json()
else:
    problem = resp.json()
    match problem.get("code"):
        case "insufficient_balance":
            notify_user("Balansni to'ldiring")
        case "out_of_stock" | "service_unavailable":
            try_another_country()
        case "rate_limited" | "upstream_unavailable":
            retry_later(int(resp.headers.get("Retry-After", 5)))
        case _:
            log.error("MilliySavdo xatosi %s (%s)", problem.get("code"), problem.get("request_id"))

API xato kodlari#

code	HTTP	Ma'nosi	Nima qilish kerak
invalid_request	400	So'rov noto'g'ri	So'rov formatini tekshiring (detail da sabab). Qayta yuborishdan oldin tuzating.
validation_error	422	Maydonlar tekshiruvdan o'tmadi	errors[] dagi field/message bo'yicha maydonlarni tuzating.
authentication_required	401	API kalit berilmagan	Authorization: Bearer <kalit> headerini qo'shing.
invalid_api_key	401	API kalit yaroqsiz	Kalit to'liq va to'g'ri nusxalanganini tekshiring; kerak bo'lsa yangisini yarating.
api_key_expired	401	API kalit muddati tugagan	Kabinetda yangi kalit yarating yoki rotatsiya qiling.
api_key_revoked	401	API kalit bekor qilingan	Kalit bekor qilingan — yangi kalit yarating.
api_key_in_query	400	API kalit URL'da yuborilmasin	Kalitni URL dan olib tashlang va faqat Authorization headerida yuboring. Kalitni rotatsiya qiling — u loglarga tushgan bo'lishi mumkin.
insufficient_scope	403	Kalitda bu amal uchun ruxsat yo'q	Kerakli scope bilan yangi kalit yarating (masalan, orders:write).
live_access_not_granted	403	Production ruxsati berilmagan	Production ruxsatiga ariza bering yoki test kalitdan foydalaning.
client_suspended	403	Akkaunt vaqtincha to'xtatilgan	Kabinetdagi banner'da sabab va muddat ko'rsatilgan. Savollar bo'lsa qo'llab-quvvatlashga yozing.
client_blocked	403	Akkaunt bloklangan	Qo'llab-quvvatlash xizmatiga murojaat qiling.
ip_not_allowed	403	IP manzil ruxsat ro'yxatida yo'q	So'rovni ruxsat etilgan server IP sidan yuboring yoki allowlist ni yangilashni so'rang.
forbidden	403	Ruxsat yo'q	Bu resursga ruxsatingiz yo'q.
not_found	404	Topilmadi	ID va yo'lni tekshiring; buyurtma boshqa rejim (test/live) kaliti bilan yaratilgan bo'lishi mumkin.
conflict	409	Holat ziddiyati	Resurs holatini qayta o'qing va amalni takrorlang.
idempotency_in_progress	409	Shu Idempotency-Key bilan so'rov hali bajarilmoqda	Birinchi so'rov tugashini kuting, so'ng o'sha Idempotency-Key bilan qayta yuboring.
idempotency_key_reused	422	Idempotency-Key boshqa so'rov uchun ishlatilgan	Har bir yangi buyurtma uchun yangi Idempotency-Key (UUID) yarating.
sms_already_received	409	SMS kod allaqachon kelgan	Bekor qilish shart emas — SMS kodni buyurtmadan oling.
order_not_cancellable	409	Buyurtmani bekor qilib bo'lmaydi	Buyurtma yakuniy holatda; GET /orders/{id} bilan holatni tekshiring.
insufficient_balance	402	Balans yetarli emas	milliysavdo.uz da balansni to'ldiring va qayta urining.
out_of_stock	409	Raqamlar tugagan	Boshqa davlatni tanlang yoki keyinroq urining (GET /prices dagi in_stock).
service_unavailable	409	Xizmat vaqtincha ishlamayapti	Xizmat vaqtincha yopiq — keyinroq yoki boshqa davlat bilan urining.
rate_limited	429	So'rovlar chegarasi oshdi	Retry-After soniya kuting; exponential backoff qo'llang.
quota_exceeded	429	Kunlik/oylik kvota tugadi	Kunlik/oylik kvota tugadi — keyingi davrni kuting yoki limitni oshirishni so'rang.
order_limit_reached	429	Buyurtmalar chegarasi oshdi	Faol buyurtmalar tugashini kuting yoki kunlik limit yangilanishini kuting.
too_many_failed_orders	429	SMS kelmagan buyurtmalar ko'p — vaqtincha cheklov	SMS kelmagan buyurtmalar ko'p — xizmat/davlat tanlovini tekshiring, cheklov vaqtincha.
temporarily_blocked	429	Shubhali trafik — vaqtincha cheklov	Retry-After'ga amal qilmay juda ko'p so'rov yuborildi — ko'rsatilgan vaqt kuting va backoff qo'shing.
upstream_unavailable	503	Operator bilan aloqa yo'q	Operator bilan aloqa yo'q — biroz kutib, backoff bilan qayta urining.
internal_error	500	Ichki xato	Qayta urining; takrorlansa request_id bilan bizga yozing.

Kabinet (portal) xato kodlari#

Bu kodlar faqat dasturchilar kabineti API sida uchraydi.

code	HTTP	Ma'nosi	Nima qilish kerak
session_required	401	Portal sessiyasi yo'q yoki tugagan	Kabinet: qaytadan kiring.
csrf_failed	403	So'rov manbasi tasdiqlanmadi	Kabinet: sahifani yangilang va qayta urining.
invalid_grant	400	SSO kodi yaroqsiz yoki muddati tugagan	Kabinet: kirish kodi eskirgan — qayta kiring.
webhook_url_rejected	422	Webhook manzili qabul qilinmadi	Ommaviy https:// manzil kiriting (localhost/xususiy IP taqiqlangan).
limit_reached	409	Chegara: yangi obyekt yaratib bo'lmaydi	Obyektlar soni limitga yetgan — keraksizlarini o'chiring.