Каталарды иштетүү жана статус коддору

1) Эмне үчүн каталарды стандартташтыруу

• маселенин түрүн коддойт,
• жардам берет (мындан ары эмне кылуу керек),
• ички бөлүктөрүнүн агып кетишинен коргойт,
• менен шайкеш келет.

2) Дизайн принциптери

1. Бардык кызматтар үчүн бир ката схемасы (REST/GraphQL/gRPC/webhooks).
2. Ретрайлардын так семантикасы: кайсы коддорду ретрациялоо керек, кайсынысы - жок.
3. write-иш-Fail-closed: жакшы 4xx/5xx тынч туруксуздук караганда.
4. Агып жок: SQL, Stack, Cookies, ички ID ачыкка жок.
5. Tracking: ар дайым кайра 'trace _ id '/' correlation _ id'.
6. Билдирүүлөрдү локалдаштыруу - кошумча, бирок 'reason' коддору туруктуу бойдон калууда.

3) Бирдиктүү формат (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' - ката классынын туруктуу URL идентификатору.
• 'code' - домендин кыска машина коду (релиздердин ортосунда туруктуу).
• 'hint' - кардарга эмне кылуу керек (кайталоо, токенди жаңыртуу, параметрлерди өзгөртүү).
• 'meta' - коопсуз деталдар (сырсыз жана PII).

4) Статус коддору картасы (минималдуу топтому)

Аутентификация/авторизация

400 Bad Request - структуралык валидация/схема.
401 Unauthorized - жок/белгисиз токен. Кошуу 'WWW-Authenticate'.
403 Forbidden - аутентификацияланган, бирок эч кандай укук/саясатчылар баш тарткан.
404 Not Found - укуктар жок болсо, ресурстун бар экенин жашыруу.
409 Conflict - версиялардын/шарттардын карама-каршылыгы (optimistic lock, idempotentity).
451 Unavailable For Legal Reasons - комплаенс/юрисдикция блогу.

Лимиттер жана коргоо

408 Request Timeout - кардар өтө жай орган жөнөтөт.
409/425 Too Эрте - 0-RTT/TLS 1 эрте кайталоо тыюу салуу. 3.
429 Too Many Requests - 'Retry-After' жана лимит саясаты менен.
499 Client Closed Request - (периметри боюнча/NGINX) кардар байланыш үзүлгөн.

Маалыматтар жана бизнес эрежелери

422 Unprocessable Content - бизнес-валидация схемадан өттү, бирок мааниси туура эмес.
423 Locked - ресурс бөгөттөлгөн (KYC review, AML freeze).
409 Conflict - кош жөнөтүү, жарыш, мамлекеттик чеги (мисалы, "буга чейин иштеп жатат").
410 Gone - End Point/Resource алынып салынды (депрекейт аяктады).

Сервердик

500 Internal Server Error - белгисиз ката; майда-чүйдөсүнө чейин айтпай.
502 Bad Gateway - көз карандылык ката/прокси кайтып келди.
503 Service Unavailable - деградация/пландаштырылган иш; кошуу 'Retry-After'.
504 Gateway Timeout - көз карандылык убакыт.

5) Семантика ретраи жана идемпотенттүүлүк

400/ 401/403/404/422 (эгерде кардар өтүнүчтү өзгөртпөсө).
Сиз: 408/429/5xx/ 425/499/504 (backoff + jitter менен).
Демпотенттик: 'POST' үчүн 'Idempotency-Key' (UUIDv4) кирет.

кайталап аткаруунун чыр-чатак үчүн кайра 409 с 'hint: "Use same Idempotency-Key or GET status".
Сакталган натыйжаны кайтарууда 'Idempotency-Replay: true' кошуңуз.

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

6) Кирүү Validation: талаа ката түзүмү

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) Жарым-жартылай ийгиликсиздик (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) Пагинация жана "бош" жооптор

Бош чогултуу - 200 с 'items: []', эмес 404.
Барактын аягы - 'next _ page _ token' жок.
Туура эмес токен - 400 с 'code: PAGINATION_CURSOR_INVALID'.

9) Webhooks: ишенимдүү жеткирүү

Иш-чараларга кол коюңуз (HMAC) жана иштетүүгө чейин текшериңиз.
ийгиликтүү иштетүү жооп - 2xx (жакшы 204).
Алуучунун убактылуу мүчүлүштүктөрү - 5xx; жөнөтүүчү кайталайт (экспоненциалдык backoff, життер).
'event _ id' боюнча дедупликация жана натыйжаны сактоо (idempotent consumer).
Жараксыз payload - 400/422 кайталоосуз.

10) протоколдорго ылайык (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"]
}]
}

Сынчыл каталар үчүн 200 эмес, тиешелүү HTTP кодун колдонуу сунушталат.

11) Кардарга аталыштар жана кеңештер

'Retry-After' - секунд/NTTR-датасы (429/503/425/408).
'Warning' - жумшак деградация же депрекейт ("199 - Feature X is deprecated").
`Deprecation`, `Sunset`, `Link: <...>; rel = "deprecation" '- башкарылуучу өчүрүү үчүн.
'Problem-Type' (өзгөчө) - кардар боюнча каталарды тез роутинг.
'X-Trace-Id '/' Correlation-Id' - логин/сооданы байланыштырат.

12) Билдирүү коопсуздугу

Кирүү сырларын (токендер/кол тамгалар) жооп денесинде кайталабаңыз.
PAN/PII ('1234') жашыруу.
401/403 үчүн - кайсы атрибут ишке ашпай калганын ачыктабаңыз.
Үчүн 404 ордуна "resource exists but not yours" - жөн гана 404.

13) ката байкоо

• `http_errors_total{status, route, tenant}`
• 'error _ classes _ total {code}' ('code' денеден)
• үлүшү 429, 5xx; 'p95 '/' p99' latency өзүнчө ката жооптор үчүн
• 'retry _ after _ seconds _ bucket' - кайталоо кеңештеринин гистограммасы

• жоопту 'trace _ id' менен байланыштырыңыз, 'code', 'type', 'status', 'route', 'tenant', PIIсиз сактаңыз.

• 5xx _ rate> X% 'RPS боюнча> N;
• критикалык каттамдар боюнча 429 өсүшү;
• 'timeout/504' у көз карандылыгы;
• тез-тез 409/idempotentity → жарыш белгиси.

14) Мисалдар

14. 1 422 (бизнес-валидация)

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 (Демпотенттик)

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 (лимиттер)

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) Антипаттерндер

200 дене ката тексти менен кайтаруу.
Кызматтардын ортосундагы каталардын ар кандай форматтарын аралаштыруу.
Stack/SQL/таблицалардын аттарын/ички URL 'дерди' detail 'ге ачуу.
Туруктуу 'code '/' type' ордуна 'message' колдонуңуз.
Күтүлгөн бизнес ката менен 500 кайтаруу (мисалы, "баланс жетишсиз").
REST/GraphQL/gRPC ортосундагы ыраатсыз семантика.

16) iGaming/каржы өзгөчөлүктөрү

KYC/AML/жазалардын үчүн так коддору: 'KYC _ REQUIRED', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
Юрисдикциялардын чектөөлөрү: 451 тизмесин көрсөтпөстөн коопсуз формулировкасы менен.
Акча-write бүтүмдөр: 409/423 атаандаштык жана бөгөт коюу менен, кайталоо терезе менен 'hint'.
Оюнчунун лимиттеринин инварианттары: жоопкерчиликтүү төлөмдөрдүн эрежелерин бузуу үчүн 422 колдонуңуз.
Аудит: өзгөрүлбөгөн чечим журналдары (код, убакыт, актёр, trace_id).

17) Prod-даярдык чек тизмеси

• Бирдиктүү JSON ката схемасы, туруктуу 'type '/' code'.
• Mapping HTTP gRPC/GraphQL макулдашылган жана документтештирилген.
• Retry семантикасы + 'Retry-After'; write үчүн демпотенттик.
• PII/сырларды жашыруу; 404 ресурстарды жашыруу үчүн.
• Ката Метрика жана Алерт; 'trace _ id' менен корреляция.
• Депрекейт саясаты: 'Deprecation', 'Sunset', 'Link'.
• Тесттер: negative/fuzz, нускаларынын чыр-чатак, көз карандылыктын кулашы, эки тараптуу.
• Колдонмо кардарларга: 409/422/429/5xx арткы жана иштетүү мисалдар.

18) TL; DR

c 'type '/' code '/' trace _ id' каталарынын бирдиктүү JSON форматын стандартташтыруу, туура HTTP коддорун колдонуу, валидацияны (400/422), (401/403/404 укуктарын), чыр-чатактарды/демпотенттикти (409) жана чектерди (429) айырмалоо. Келгиле, так 'Retry-After' жана 'hint', сезимтал маалыматтарды жашыруу, каталарды 'trace _ id' менен жаздыруу жана 5xx/429/p99 боюнча алерттерди куруу.