Идоракунии хатогӣ ва рамзҳои ҳолат

1) Чаро хатогиҳоро стандартӣ кунед

• пешгӯӣ навъи мушкилотро рамзгузорӣ мекунад,
• ба муштарӣ дархостҳои дуруст медиҳад (чӣ бояд кард),
• аз ихроҷи қисмҳои дохилӣ муҳофизат мекунад,
• мувофиқ бо retras ва idempotency.

2) Принсипҳои тарроҳӣ

1. Як схемаи хатогӣ барои ҳамаи хидматҳо (REST/Graph

2. Семантикаи дақиқи ретрейҳо: кадом рамзҳоро бозпас мегирад, ки ин тавр нест.
3. Амалиёти хаттӣ дар навиштан: беҳтар аз 4xx/5xx нисбат ба номутобиқатии ором.
4. Ягон ихроҷ нест: SQL, стекҳо, конфигуратсияҳо, ID-ҳои дохилиро ифшо накунед.
5. Пайгирӣ - Ҳамеша 'trace _ id '/' correlation _ id' -ро бармегардонед.
6. Маҳаллисозии паёмҳо ихтиёрӣ аст, аммо рамзҳо ва 'reason' устувор боқӣ мемонанд.

3) Формати ягона (Тафсилоти мушкилот/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.
• 'код' - рамзи мошини домени кӯтоҳ (дар байни релизҳо устувор аст).
• 'ишора' - барои муштарӣ чӣ бояд кард (такрор, аломати навсозӣ, параметрҳои тағирот).
• 'meta' - қисмҳои бехатар (бе асрор ва PII).

4) Харитаи рамзи ҳолат (маҷмӯи ҳадди аққал)

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

400 Дархости бад - тасдиқи/нақшаи сохторӣ.
401 беиҷозат - аломати беэътибор. Илова кардани 'WWW-аутентификатсия'.
403 мамнӯъ - тасдиқшуда, аммо ҳеҷ гуна ҳуқуқ/сиёсат рад карда нашудааст.
404 Ёфт нашуд - мавҷудияти манбаъро бидуни ҳуқуқ ниқоб кунед.
409 Низоъ - муноқишаи версия/давлатӣ (қулфи оптимистӣ, аблаҳӣ).
451 Бо сабабҳои ҳуқуқӣ дастнорас аст - Блоки мувофиқат/салоҳият.

Маҳдудиятҳо ва муҳофизат

408 Вақти дархостро дархост кунед - Мизоҷ баданро хеле суст мефиристад.
409/425 Хеле барвақт - манъи такрори барвақт дар 0-RTT/TLS 1. 3.
429 Дархостҳои аз ҳад зиёд - бо 'Retry-After' ва сиёсати маҳдуд.
499 Дархости пӯшидаи муштарӣ - (дар периметр/NGINX) муштарӣ пайвастшавиро қатъ кард.

Маълумот ва қоидаҳои тиҷорат

422 Мундариҷаи бебозгашт - тасдиқи тиҷорат аз нақша гузашт, аммо маъно нодуруст аст.
423 Қулф карда шудааст - захираҳо баста шудаанд (баррасии KYC, яхкунӣ AML).
409 Низоъ - пешниҳоди дукарата, нажод, маҳдудияти вазъ (масалан, "аллакай дар ҷараён аст").
410 Gone - нуқтаи ниҳоӣ/манбаъ нест карда шуд (фарсудашавии пурра).

Хидматрасон

500 Хатои сервери дохилӣ - хатои номаълум; тафсилотро ифшо намекунад.
502 Дарвозаи бад - вобастагӣ хатогӣ/проксингро баргардонд.
503 Хизматрасонӣ дастнорас - корҳои таназзул/банақшагирифташуда; илова 'Retry-After'.
504 Вақти дарвоза.

5) Семантикаи ретрей ва аблаҳӣ

Шумо 400/ 401/403/404/422 бозпас гирифта наметавонед (агар муштарӣ дархостро иваз накарда бошад).
Шумо метавонед бозпас гиред: 408/429/5xx/ 425/499/504 (бо backoff + jitter).
Idempotency: Барои 'POST', 'Idempotency-Key' -ро фаъол созед (UUID 'v4).

Барои муноқишаи такрорӣ, 409-ро бо ишора баргардонед: "Ҳамон як Idempotency-Key ё GET -ро истифода баред" '.
Иловаи 'Idempotency-Replay: true' when, ки натиҷаи захирашударо бармегардонад.

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

6) Тасдиқи вуруд: сохтори хатои майдон

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) Хатогиҳои қисман (нокомии партия/қисман)

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

8) Ҷавобҳои пагоҳӣ ва "холӣ"

Ҷамъоварии холӣ - 200 адад: [] ', на 404.
Охири саҳифа - 'next _ page _ token' мавҷуд нест.
Аломати нодуруст - рамзи 400 с: PAGINATION_CURSOR_INVALID'.

9) Вебхукҳо: Таҳвили боэътимод

Ба рӯйдодҳо имзо гузоред (HMAC) ва пеш аз коркард тафтиш кунед.
Ҷавоб ба коркарди бомуваффақият 2xx (беҳтарин 204) мебошад.
Хатогиҳои муваққатии қабулкунанда - 5xx; фиристанда такрор мекунад (пушти экспоненсиалӣ, ҷиттер).
Ҷойгиркунӣ аз ҷониби 'event _ id' ва сарфа кардани натиҷа (истеъмолкунандаи номатлуб).
Сарбории нодуруст - 400/422 такрорӣ нест.

10) Мутобиқати протокол (g

• 'ИНВАЛИД _ АРГУМЕНТ' → 400
• 'UNAUTHENTICATED' → 401
• 'ИҶОЗАТ _ РАД КАРДА ШУД' → 403
• 'НЕ _ ЁФТ' → 404
• 'ALLECT _ EXISTS' → 409
• 'НОКОМ _ ПЕШГУФТОР' → 412/422
• 'RESOURCE _ EXHAUSTED' → 429
• 'ABORTED' → 409
• 'UNAVAILABLE' → 503
• 'МӮҲЛАТИ НИҲОӢ _ ЗИЁД' → 504

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

Тавсия дода мешавад, ки ба ҷои 200 барои хатогиҳои интиқодӣ рамзи дахлдори HTTP истифода шавад.

11) Унвонҳо ва маслиҳатҳои муштариён

'Retry-After' - сонияҳо/санаи HTTP (429/503/425/408).
'Огоҳӣ' - таназзули мулоим ё беқурбшавӣ ("199 - Хусусияти X депрессия аст").
'Пастшавӣ', 'Ғуруби офтоб', 'Истинод: <...>; rel = "фарсудашавӣ" '- барои хомӯш кардани назорат.
'Навъи мушкилот' (одат) - хатои зуд ба муштарӣ.
'X-Trace-Id '/' Correlation-Id' - пайвандҳо/пайҳо.

12) Амнияти паём

Асрори вурудро (нишонаҳо/имзоҳо) дар бадани вокуниш такрор накунед.
Маска PAN/PII ('1234').
Барои 401/403 - ифшо накунед, ки кадом хусусият ноком аст.
Барои 404, ба ҷои "манбаъ вуҷуд дорад, аммо на аз они шумо" - ҳамагӣ 404.

13) Риояи хатогиҳо

• 'http _ хатогиҳо _ total {вазъ, масир, иҷорагир}'
• 'error _ classes _ total {code}' (бо 'рамз' аз бадан)
• мубодила 429, 5xx; 'p95 '/' p99' таъхир барои ҷавобҳои хато алоҳида
• 'retry _ after _ seconds _ сатил' - гистограммаи маслиҳатҳои такрорӣ

• ҷавобро бо 'trace _ id', нигоҳ доштани 'рамз', 'намуди', 'ҳолат', 'масир', 'иҷорагир', PII пайваст кунед.

• хӯшае '5xx _ rate> X%' дар RPS> N;
• афзоиши 429 дар масирҳои муҳим;
• вобастагии 'вақт/504' of;
• зуд-зуд 409/idempotency → аломати мусобиқа.

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 бо матни хатои бадан.
Форматҳои хатогии гуногунро дар байни хидматҳо омехта кунед.
Васеъ кардани стек/SQL/номҳои ҷадвал/URL-ҳои дохилӣ дар 'detail'.
'Паём' -ро ба ҷои 'коди '/' навъи' устувор истифода баред.
Ҳангоми хатогии интизорравандаи тиҷорат 500-ро баргардонед (масалан, "тавозун нокифоя аст").

Семантикаи номувофиқ байни REST/Graph

16) Хусусиятҳои IGaming/Finance

Рамзҳои тоза барои KYC/AML/таҳримҳо: 'KYC _ ЛОЗИМ', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
Маҳдудиятҳои ҳуқуқӣ: 451 бо матни бехатар бидуни рӯйхат.
Амалиёти навиштани пул: 409/423 барои рақобат ва қуфлҳо, 'ишора' бо равзанаи сурх.
Бозингар инвариантҳоро маҳдуд мекунад: 422-ро барои вайрон кардани масъулияти пардохт истифода баред.
Аудит: гузоришҳои ҳалли тағйирнопазир (рамз, вақт, актер, trace_id).

17) Рӯйхати санҷиши омодагии Prod

• Нақшаи хатои ягонаи JSON, 'намуди '/' коди устувор.
• HTTP ↔ g
• Retray semantics + 'Retry-After'; idempotency барои навиштан.
• PII/ниқоби махфӣ; 404 барои пинҳон кардани захираҳо.
• Ченакҳои хатогӣ ва ҳушдор; робита бо 'trace _ id'.
• Сиёсати амортизатсия: 'Амортизатсия', 'Ғуруби офтоб', 'Пайванд'.
• Санҷишҳо: манфӣ/фюз, муноқишаи версия, тарки вобастагӣ, пешниҳоди дукарата.
• Роҳнамои муштариён: Намунаҳои бозгашт ва коркарди 409/422/429/5xx.

18) TL; ДР

Формати ягонаи хатогии JSON-ро бо 'type '/' code '/' trace _ id' стандартӣ кунед, рамзҳои дурусти HTTP-ро истифода баред, байни санҷиш (400/422), ҳуқуқҳои (401/403/404), низоъҳо/номутобиқатӣ (409) ва маҳдудиятҳо (429) фарқ кунед. 'Retry-After' ва 'ишора' -ро равшан кунед, маълумоти ҳассосро ниқоб кунед, хатогиҳои сабти номро бо 'trace _ id' гузоред ва огоҳиҳоро бо 5xx/429/p99 созед.