Xato kodlari va best practices

1) Xatolarni nima uchun standartlashtirish kerak

Mijozlar uchun oldindan aytish mumkin: retrajlarning yagona formati va xulq-atvori.
Debagni tezlashtirish:’trace _ id ’/’ request _ id’, barqaror’error _ code’.
Xavfsizlik: SQL/stack traces/konfigi sizib chiqmaydi.
Kuzatilganlik: xatolar taksonomiyasi bo’yicha hisobot (validatsiya, kvotalar, taymautlar va boshqalar).

2) Bazaviy prinsiplar

1. Barcha 4xx/5xx uchun yagona javob formati (va 2xx uchun qisman xato - alohida sxema).
2. Aniq semantika HTTP: to’g’ri maqom eng muhimi.
3. Ikki darajali kod: transport (’status’) va domen barqaror’error _ code’.
4. Retriable vs Non-retriable: aniq ko’rsating va qo’ng’iroq qiling.
5. Andoza xavfsizlik: tafsilotlar - faqat huquqli mijoz uchun; ichki yo’llarsiz.
6. Mahalliylashtirish: mashina kodi barqaror bo’lib qoladi, matn tarjima qilinadi.

3) Xatoning yagona formati (RFC 7807 asosida)

json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}

Majburiy:’type’,’title’,’status’,’error _ code’,’trace _ id’.
Ixtiyoriy:’errors []’,’retriable’,’hint’,’meta’.

• `Content-Type: application/problem+json`
• `X-Request-ID`/`Traceparent` (W3C)
• (429/503 uchun)’Retry-After’(soniya yoki sana)

4) HTTP maqomlari semantikasi («klassika» va amaliyotni birlashtirish)

2xx (nuanslar bilan muvaffaqiyat)

200 OK - oddiy muvaffaqiyat.
201 Created - yaratilgan resurs (Location).
202 Accepted - navbatda asinxron (bering’status _ url’).
207 Multi-Status - qisman muvaffaqiyat (iloji boʻlsa, qoching).

4xx (mijoz xatosi)

400 Bad Request - sintaksis/format, lekin maydon validatsiyasi emas (yaxshiroq 422).
401 Unauthorized - yoʻq/notoʻgʻri token. «WWW-Authenticate» ni oling.
403 Forbidden - token validen, lekin huquqlar yetarli emas (RBAC/ABAC/limitlar).
404 Not Found - resurs/endpoint mavjud emas.
409 Conflict - versiya/holat toʻqnashuvi (optimistic locking, idempotency).
410 Gone - endpoint abadiy olib tashlandi.
412 Precondition Failed - ETag/If-Match muvaffaqiyatsiz tugadi.
415 Unsupported Media Type - notoʻgʻri’Content-Type’.
422 Unprocessable Entity - biznes qoidalarining validatsiyasi.
429 Too Many Requests - kvotalar/tezlikdan oshib ketdi (§ 7 ga qarang).

5xx (server xatosi)

500 Internal Server Error - to’satdan xato; tafsilotlarni oshkor qilmaslik.
502 Bad Gateway - apstrim xatosi.
503 Service Unavailable - degradatsiya/qayta yuklash, bering’Retry-After’.
504 Gateway Timeout - orqa taymaut.

5) Domen taksonomiyasi’error _ code ’

• ’AUTH _’ - autentifikatsiya/avtorizatsiya.
• ’VAL _’ - kirish ma’lumotlarini validatsiya qilish.
• ’RATELIMIT _’ - kvotalar va tezlik.
• ’IDEMP _’ - idempotentlik/dublikatlar.
• ’CONFLICT _’ - versiyalar/holat.
• ’DEP _’ - bogʻliqlik (PSP/DNS/SMTP).
• «PAY _» - to’lov domenining biznes xatolari.
• ’SEC _’ - xavfsizlik (imzolar, HMAC, mTLS).
• ’INT _’ - ichki to’satdan.

• Vaqt barqarorligi (back-compat).
• Xatolar katalogidagi tavsiflar va misollar (docs + machine-readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• Agar’true’- albatta’Retry-After’(soniyada) yoki kontrakt «eksponensial bek-off (1-2 s, maks. 30-60 s)».

Retriable odatda:’502/503/504’, baʼzi’500’,’429’(oynadan keyin).
Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate limit & quota xatolari (429)

json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}

• `Retry-After: 12`
• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
• Для квот: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`

8) Idempotentlik va nizolar

Yozuv so’rovlarida - «Idempotency-Key» (24-72 soat ichida noyob).
Qayta ishlash mojarosi → 409 Conflict s’error _ code: "IDEMP_REPLAY"'.
Resursning ETag → 412 Precondition Failed versiyasi mojarosi.
Javobda xavfsiz qayta soʻrash uchun’resource _ id ’/’ status _ url’ilova qiling.

9) Validatsiya va 422

json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}

• Biznes-validatsiya uchun xuddi shunday 400 - 422 ga takrorlamang.
• Xabarlarni oʻqish mumkin;’code’- mashinada.

10) Xatolar xavfsizligi

Hech qachon: stack traces, SQL, fayl yoʻllari, shaxsiy xost nomlari.
PII tahrirlang; GDPR/DSAR’ni kuzatib boring.
Imzo uchun/NAMAS:’SEC _ SIGNATURE _ MISMATCH’(403) va’SEC _ TIMESTAMP _ SKEW’(401/403) ni «5 daqiqa ± vaqtni tekshiring».

11) Korrelyatsiya va kuzatish

Har doim’trace _ id ’/’ X-Request-ID’qoʻshing va loglar/trassalarga tashlang.
Xatolarni’error _ code’va’status’→ «top-xatolar», «new vs known» dashbordlari orqali birlashtiring.
Alertlar: 5xx/422/429, yashirin p95, share of errors.

12) gRPC/GraphQL/Webhooks - mappinglar

gRPC ↔ HTTP

GraphQL

Transport 200, lekin’errors []’ichida -’extensions’qoʻshing. code` и `trace_id`.
«Fatal» (autentifikatsiya/kvota) uchun - haqiqiy HTTP 401/403/429 yaxshiroqdir.

Webhooks

Faqat 2xx oluvchini muvaffaqiyatli deb hisoblang.
Eksponensial bek-off,’X-Webhook-ID’,’X-Signature’retralari.
Oluvchidan 410 - retrajni to’xtatish (endpoint o’chirilgan).

13) Xatolarni versiyalash

’type ’/’ error _ code’ - barqaror; Yangilarini faqat qoʻshish.
Tana sxemasini o’zgartirganda - API yoki’problem + json ning minor versiyasini ko’taring; v=2`.
Hujjatlar: kodlar jadvali + misollar; changelog xatolari.

14) Hujjatlar (OpenAPI parchalari)

Global javoblar

yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }

Endpoint misoli

yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }

15) Test sinovi va sifat

Kontrakt-testlar: muvofiqlik’application/problem + json’, majburiy maydonlar.
Negative tests: barcha tarmoqlar 401/403/404/ 409/422/429/500.
Chaos/latency: retraylarni 5xx/ 503/504/429 (’Retry-After’) da tekshirish.
Security tests: ichki xabar yo’qligi, to’g’ri PII niqobi.
Backward-compat: Eski mijozlar yangi maydonlarni tushunishadi (qo’shing, buzmang).

16) Joriy etish chek-varaqasi

• Yagona’problem + json’+ barqaror’error _ code’.
• Toʻgʻri semantika HTTP/gRPC/GraphQL.
• Retriable/non-retriable +’Retry-After ’/back-off tavsiyalari.
• Rate-limit sarlavhalari va 429 xatti-harakatlari.
• Idempotentlik (’Idempotency-Key’, 409/412).
• Xavfsizlik: stack traces/sirlarsiz, PII tahriri.
• ’trace _ id ’/’ X-Request-ID’barcha xatolarda.
• Xatolar katalogi hujjatlari va misollar.
• Xatolar taksonomiyasi bo’yicha monitoring.
• Salbiy stsenariylarning avtotestlari.

17) Mini-FAQ

422 dan 400 qanday farq qiladi?
400 - singan so’rov (sintaksis/tarkib turi). 422 - sintaksis bo’yicha haqiqiy, ammo biznes-qoidalar o’tmadi.

Qachon 401, qachon 403?
401 - yo’q/noto’g "ri token; 403 - token bor, huquqlar yetarli emas.

Har doim’Retry-After’kerakmi?
429/503 uchun - ha; qolganlari uchun retriable - aniq tavsiya berish maqsadga muvofiqdir.

Jami

Yaxshi ishlab chiqilgan xatolar - bu to’g’ri HTTP maqomi, yagona’problem + json’, barqaror’error _ code’, retrajlar bo’yicha aniq maslahatlar va qat’iy xavfsizlik. Formatni standartlashtiring, taksonomiyani hujjatlashtiring, telemetriya va testlarni qo’shing va APIingiz oldindan aytib bo’ladigan, xavfsiz va integratorlarga do’stona bo’ladi.