Қателерді өңдеу және мәртебе кодтары

1) Қателерді стандарттаудың қажеті

Бірыңғай келісім шарт қателіктерді жеделдетеді, жалған ретрацияны азайтады және RCA-ны жаңғыртуға болады. Жақсы жүйе:

мәселенің түрін алдын ала кодтайды,
клиентке қолданылып жүрген кеңестерді береді (бұдан әрі не істеу керек),
ішкі бөлшектердің ағуынан қорғайды,
ретраға және іспеттілікке сәйкес келеді.

2) Дизайн қағидаттары

1. Барлық сервистер үшін бір қате схемасы (REST/GraphQL/gRPC/webhooks).
2. Ретрайлардың нақты семантикасы: қандай кодтарды ретрациялайды, қайсысын - жоқ.
3. write-операцияларында Fail-closed: 4xx/5xx тыныш тұрақсыздыққа қарағанда жақсы.
4. Ағындарсыз: SQL, ағындарды, конфигаларды, ішкі ID ашпаңыз.
5. Трассировка: әрқашан 'trace _ id '/' correlation _ id' дегенді қайтарыңыз.
6. Хабарларды оқшаулау - қосымша, бірақ 'reason' кодтары тұрақты болып қалады.

3) Бірыңғай пішім (Problem Details/JSON)

Ұсынылатын базалық формат (RFC 7807 үйлесімді):

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, теңсіздік).
451 Unavailable For Legal Reasons - комплаенс/юрисдикция бойынша блок.

Лимиттер және қорғау

408 Request Timeout - клиент денені өте баяу жібереді.
409/425 Too Early - 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 - эндпоинт/ресурс жойылды (депрекейт аяқталды).

Серверлік

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

💡 Ереже: күдік кезінде write-операциялар → 409 (жанжал) немесе 503 (кейінірек қайталау), 200 емес.

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' дегенді қосыңыз.

429-дағы headers мысалы:


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

6) Кіру валидациясы: өріс қателерінің құрылымы

400/422 үшін өріс қателерінің жиынын пайдаланыңыз:

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)

Батч-эндпоинттерде қателерді құрылымсыз 200 ішінде жасырмаңыз. Әрбір тапсырманың өз мәртебесі бар нәтижелер массивімен 207 Multi-Status немесе 200 қайтарыңыз:

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)

gRPC → HTTP:

`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

GraphQL: әрқашан көліктік деңгейде 200 рұқсат етіледі, бірақ қателерді 'errors []' ішіне қойыңыз және тақырыптарда/кеңейтулерде қайталаңыз:

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

Сыни қателер үшін 200 емес, тиісті HTTP кодын пайдалану ұсынылады.

11) Клиенттің тақырыптары мен кеңестері

'Retry-After' - секунд/НТТР-күні (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-сіз сақтаңыз.

Алерталар:

RPS> N кезінде '5xx _ rate> X%' екпіні;
шекті бағыттарда 429 өсім;
тәуелділіктің 'timeout/504';
жиі 409/икемділік → жарыс белгісі.

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 дегенді денедегі қате мәтінімен қайтару.
Серверлер арасында түрлі қате пішімдерін араластыру.
'detail' ішіндегі/SQL/кесте атаулары/ішкі URL стегін ашу.
Тұрақты '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'.
HTTP gRPC/GraphQL Mapping келісілген және құжатталған.
Ретрайлардың семантикасы + 'Retry-After'; write үшін теңсіздік.
PII/құпияларды бүркемелеу; 404 ресурстарды жасыру үшін.
Қателер мен тәуекелдер өлшемдері; 'trace _ id' корелляциясы.
Депрекейт саясаты: 'Deprecation', 'Sunset', 'Link'.
Тесттер: negative/fuzz, нұсқа қайшылығы, тәуелділіктің төмендеуі, double-submit.
Клиенттерге жол: 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 бойынша қателерді жасаңыз.

Қателерді өңдеу және мәртебе кодтары

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

Лимиттер және қорғау

Деректер және бизнес-ережелер

Серверлік

Бізбен байланысыңыз

Жылдам байланыс

Бейне жақында жаңартылады

Қазір біз жобалармен өте қатты айналысып жатырмыз