Xatolarni qayta ishlash va maqom kodlari

1) Xatolarni nima uchun standartlashtirish kerak

• muammo turini oldindan aytib beradi,
• mijozga amalda bo’lgan maslahatlarni beradi (bundan keyin nima qilish kerak),
• ichki detallarning sizib chiqishidan himoya qiladi,
• retralar va idempotentlik bilan mos keladi.

2) Dizayn prinsiplari

1. Barcha servislar uchun bitta xato sxemasi (REST/GraphQL/gRPC/webhooks).
2. Retrajlarning aniq semantikasi: qaysi kodlarni retraj qilish kerak, qaysi kodlarni retraj qilish kerak emas.
3. Write operatsiyalarida fail-closed: 4xx/5xx sukut saqlashdan yaxshiroqdir.
4. Oqib chiqmaydigan: SQL, stakan, konfig, ichki identifikatorni ochib boʻlmaydi.
5. Trace: har doim’trace _ id ’/’ correlation _ id’ni qaytaring.
6. Xabarlarning lokalizatsiyasi ixtiyoriy, ammo’reason’kodlari barqaror boʻlib qolmoqda.

3) Yagona format (Problem Details/JSON)

json
{
"type": "https://errors.example.com/auth/invalid-token",
"title": "Invalid access token",
"status": 401,
"code": "AUTH_INVALID_TOKEN",
"detail": "Token expired or signature invalid.",
"instance": "/api/v1/payments/12345",
"trace_id": "01HX3...ABC",
"hint": "Obtain a new token via OAuth2 refresh.",
"meta": {
"scope": "payments:write",
"policy": "deny-by-default"
}
}

• ’type’ - xato sinfining barqaror URL identifikatori.
• ’code’ - qisqa domen kodi (relizlar orasida barqaror).
• ’hint’ - mijozga nima qilish kerak (takrorlash, tokenni yangilash, parametrlarni oʻzgartirish).
• ’meta’ - xavfsiz detallar (sirsiz va PIIsiz).

4) Maqom kodlari xaritasi (minimal to’plam)

Autentifikatsiya/avtorizatsiya

400 Bad Request - tarkibiy validatsiya/sxema.
401 Unauthorized - no/nevaliden token. ’WWW-Authenticate’ qoʻshing.
403 Forbidden - autentifikatsiyalangan, lekin hech qanday huquq/siyosat rad etilgan.
404 Not Found - agar huquqingiz bo’lmasa, resursning mavjudligini yashiring.
409 Conflict - versiyalar/holatlar to’qnashuvi (optimistic lock, idempotentlik).
451 Unavailable For Legal Reasons - komplayens/yurisdiksiya bo’yicha blok.

Limitlar va himoya

408 Request Timeout - mijoz tanani juda sekin jo’natadi.
409/425 Too Early - 1- 0-RTT/TLS erta takrorlashni taqiqlash. 3.
429 Too Many Requests - «Retry-After» va limit siyosati bilan.
499 Client Closed Request - (perimetrda/NGINX) mijoz ulanishni uzdi.

Ma’lumotlar va biznes-qoidalar

422 Unprocessable Content - biznes-validatsiya sxemadan o’tdi, ammo ma’no noto’g’ri.
423 Locked - manba bloklangan (KYC review, AML freeze).
409 Conflict - ikki marta jo’natish, poyga, holat limiti (masalan, «allaqachon qayta ishlanmoqda»).
410 Gone - endpoint/resurs oʻchirildi (deprekeyt tugadi).

Server

500 Internal Server Error - nomaʼlum xato; tafsilotlarni oshkor qilmaslik.
502 Bad Gateway - bogʻliqlik xato/proksatsiyani qaytardi.
503 Service Unavailable - degradatsiya/rejali ishlar; ’Retry-After’ qoʻshiladi.
504 Gateway Timeout - bog’liqlik vaqti.

5) Retraylar va idempotentlik semantikasi

400/ 401/403/404/422 ni qaytarib boʻlmaydi (agar mijoz soʻrovni oʻzgartirmasa).
408/429/5xx/ 425/499/504 (backoff + jitter bilan).
Idempotentlik:’POST’uchun’Idempotency-Key’(UUIDv4) ni kiriting.

Takrorlash uchun 409 s’hint’ni qaytaring: «Use same Idempotency-Key or GET status».
Saqlangan natijani qaytarishda’Idempotency-Replay: true’qoʻshing.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1730641030

6) Kirish validatsiyasi: maydon xatolari tuzilishi

json
{
"type": "https://errors.example.com/validation",
"title": "Validation failed",
"status": 422,
"code": "VALIDATION_ERROR",
"trace_id": "01HX4...XYZ",
"errors": [
{"field": "amount", "rule": "min", "message": "Must be >= 10"},
{"field": "currency", "rule": "enum", "message": "Unsupported currency"}
]
}

7) Qisman muvaffaqiyatsizliklar (batch/partial failure)

json
{
"status": "partial",
"succeeded": 8,
"failed": 2,
"results": [
{"id": "op1", "status": 201},
{"id": "op2", "status": 422, "error": {"code":"VALIDATION_ERROR","detail":"..."}}
]
}

8) Paginatsiya va «bo’sh» javoblar

Boʻsh kolleksiya - 200 s’items: []’, 404 emas.
Sahifaning oxiri -’next _ page _ token’mavjud emas.
Notoʻgʻri token - 400 s’code: PAGINATION_CURSOR_INVALID'.

9) Webhooks: ishonchli yetkazib berish

Hodisalarni (HMAC) imzolang va qayta ishlashdan oldin tekshiring.
Muvaffaqiyatli ishlov berish uchun javob - 2xx (yaxshiroq 204).
Oluvchining vaqtinchalik uzilishlari - 5xx; jo’natuvchi takrorlaydi (eksponensial backoff, jitter).
’event _ id’ deduplikatsiyasi va natijani saqlash (idempotent consumer).
Xato payload - 400/422 takrorlamasdan.

10) Protokollarga muvofiqlik (gRPC/GraphQL)

• `INVALID_ARGUMENT` → 400
• `UNAUTHENTICATED` → 401
• `PERMISSION_DENIED` → 403
• `NOT_FOUND` → 404
• `ALREADY_EXISTS` → 409
• `FAILED_PRECONDITION` → 412/422
• `RESOURCE_EXHAUSTED` → 429
• `ABORTED` → 409
• `UNAVAILABLE` → 503
• `DEADLINE_EXCEEDED` → 504

json
{
"data": { "createPayment": null },
"errors": [{
"message": "Forbidden",
"extensions": { "code": "FORBIDDEN", "status": 403, "trace_id": "..." },
"path": ["createPayment"]
}]
}

Tanqidiy xatolar uchun 200 emas, balki tegishli HTTP kodidan foydalanish tavsiya etiladi.

11) Mijozga sarlavhalar va maslahatlar

’Retry-After’ - soniya/NTTR-sana (429/503/425/408).
’Warning’ - yumshoq degradatsiyalar yoki deprekeyt («199 - Feature X is deprecated»).
`Deprecation`, `Sunset`, `Link: <...>; rel = «deprecation»’- boshqariladigan o’chirish uchun.
«Problem-Type» (kastom) - mijozdagi xatolarning tezkor routingi.
’X-Trace-Id ’/’ Correlation-Id’ - logi/treyslarni bog’laydi.

12) Xabarlar xavfsizligi

Javob tanasida kirish sirlarini (tokenlar/imzolar) takrorlamang.
PAN/PII (’1234’) ni yashiring.
401/403 uchun - qaysi atribut muvaffaqiyatsiz tugaganini oshkor qilmang.
404 uchun «resource exists but not yours» o’rniga - shunchaki 404.

13) Xatolar kuzatilishi

• `http_errors_total{status, route, tenant}`
• ’error _ classes _ total {code}’ (tanadan’code’boʻyicha)
• alohida xato javoblar uchun 429, 5xx;’p95 ’/’ p99’latency ulushi
• ’retry _ after _ seconds _ bucket’ - takrorlar bo’yicha maslahatlar gistogrammasi

• javobni’trace _ id’bilan bogʻlang,’code’,’type’,’status’,’route’,’tenant’, PIIsiz saqlang.

• splash’5xx _ rate> X%’RPS> N da;
• kritik yo’nalishlarda 429 ta o’sish;
• ’timeout/504’ ga bog’liqlik;
• tez-tez 409/idempotentlik → poyga belgisi.

14) Misollar

14. 1 422 (biznes-validatsiya)

json
{
"type": "https://errors.example.com/payments/limit-exceeded",
"title": "Limit exceeded",
"status": 422,
"code": "PAYMENT_LIMIT_EXCEEDED",
"detail": "Daily withdrawal limit reached for KYC1.",
"hint": "Increase limits after KYC2 or try tomorrow.",
"trace_id": "01J5...XYZ"
}

14. 2 409 (idempotentlik)

HTTP/1.1 409 Conflict
Idempotency-Replay: true

json
{
"type": "https://errors.example.com/idempotency/replay",
"title": "Duplicate request",
"status": 409,
"code": "IDEMPOTENT_REPLAY",
"detail": "A request with the same Idempotency-Key was already processed.",
"hint": "Reuse the same Idempotency-Key and GET the operation status."
}

14. 3 429 (limitlar)

json
{
"type":"https://errors.example.com/rate/too-many-requests",
"title":"Too many requests",
"status":429,
"code":"RATE_LIMITED",
"detail":"Per-key rate limit exceeded.",
"hint":"Retry after the time specified in Retry-After header."
}

15) Antipatternlar

Tanadagi xato matni bilan 200 ni qaytarish.
Xizmatlar oʻrtasida turli xato formatlarini aralashtirish.
’detail’ da jadvallar/ichki URL nomlari/SQL stekini ochish.
Barqaror’code ’/’ type’oʻrniga’message’dan foydalanish.
Kutilayotgan biznes xatosi (masalan, «balans yetarli emas») boʻlganda 500 ni qaytarish.
REST/GraphQL/gRPC orasidagi nomuvofiq semantika.

16) iGaming/Moliya xususiyatlari

KYC/AML/sanksiyalar uchun aniq kodlar:’KYC _ REQUIRED’,’KYC _ REVIEW’,’AML _ LOCK’,’SANCTION _ BLOCKED’.
Yurisdiksiya cheklovlari: 451 ro’yxat ko’rsatilmagan holda xavfsiz ifodalangan.
Pul write-operatsiyalari: raqobat va blokirovkalarda 409/423, takrorlash oynasi bilan’hint’.
O’yinchi limitlarining invariantlari: mas’uliyatli to’lovlar qoidalarini buzish uchun 422 dan foydalaning.
Audit: o’zgarmas qarorlar daftarlari (kod, vaqt, aktyor, trace_id).

17) Prod-tayyorlik chek-varaqasi

• Yagona JSON xato sxemasi, barqaror’type ’/’ code’.
• HTTP gRPC/GraphQL mapping kelishilgan va hujjatlashtirilgan.
• Retray semantikasi +’Retry-After’; write uchun idempotentlik.
• PII/sirlarni yashirish; 404 resurslarni yashirish uchun.
• Xatolar metrikasi va alertlar; ’trace _ id’ bilan korelatsiya.
• Deprekeyt siyosati:’Deprecation’,’Sunset’,’Link’.
• Testlar: negative/fuzz, versiyalar to’qnashuvi, qaramlikning pasayishi, double-submit.
• Mijozlarga yo’l qo’yish: 409/422/429/5xx.

18) TL; DR

Yagona JSON xato formatini c’type ’/’ code ’/’ trace _ id’standartlashtiring, toʻgʻri HTTP kodlaridan foydalaning, validatsiyani (400/422), (401/403/404 huquqlarini), ziddiyatlarni/idempotentlikni (409) va limitlarni (429) ajrating. Aniq’Retry-After’va’hint’ni bering, nozik ma’lumotlarni yashiring,’trace _ id’xatolarini yozing va 5xx/429/p99 bo’yicha alertlar yarating.