API қате кодтары және best practices

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

Клиенттер үшін болжамдылық: бірыңғай формат және ретрациялардың мінез-құлқы.
Дебаг жылдамдығы: 'trace _ id '/' request _ id', тұрақты 'error _ code'.
Қауіпсіздік: SQL/stack traces/конфиги ағып кетпейді.
Бақылау: қателердің таксономиясы бойынша есептілік (валидация, квоталар, таймауттар және т.б.).

2) Базалық қағидаттар

1. Барлық 4xx/5xx үшін бірыңғай жауап форматы (және ішінара қателері бар 2xx үшін - жеке схема).
2. HTTP нақты семантикасы: дұрыс мәртебе бәрінен де маңызды.
3. Кодтың екі деңгейі: көліктік ('status') және домендік тұрақты 'error _ code'.
4. Retriable vs Non-retriable: анық көрсетіңіз және бэк-офф бойынша кеңес беріңіз.
5. Әдепкі қауіпсіздік: егжей-тегжейі - тек құқықтары бар клиентке; ішкі трассасыз.
6. Оқшаулау: машина коды тұрақты болып қалады, мәтінді аудармаймыз.

3) Бірыңғай қате форматы (RFC 7807 негізінде)

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"}
}

Міндетті: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
Қосымша: 'errors []' (өрістер бойынша), 'retriable', 'hint', 'meta'.

• `Content-Type: application/problem+json`
• `X-Request-ID`/`Traceparent` (W3C)
• (429/503 үшін) 'Retry-After' (секунд немесе күн)

4) HTTP мәртебелерінің семантикасы («классика» мен практиканы біріктіру)

2xx (нюанстар табысы)

200 OK - кәдімгі табыс.
201 Created - ресурс құрылды (Location).
202 Accepted - кезектегі асинхронды (беріңіз 'status _ url').
207 Multi-Status - ішінара табыс (егер мүмкін болса, қашыңыз).

4xx (клиент қатесі)

400 Bad Request - синтаксис/пішім, бірақ өрістерді валидациялау емес (жақсы 422).
401 Unauthorized - жоқ/дұрыс емес токен. 'WWW-Authenticate' дегенді беріңіз.
403 Forbidden - токен валиден, бірақ құқықтар жеткіліксіз (RBAC/ABAC/лимиттер).
404 Not Found - ресурс/эндпоинт жоқ.
409 Conflict - нұсқалар/күй қайшылығы (optimistic locking, idempotency).
410 Gone - эндпоинт мәңгі жойылды.
412 Precondition Failed - ETag/If-Match өтпеді.
415 Unsupported Media Type - 'Content-Type' дұрыс емес.
422 Unprocessable Entity - бизнес-ережелерді валидациялау.
429 Too Many Requests - квоталар/жылдамдық асып кетті (§ 7 қараңыз).

5xx (сервер қатесі)

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

5) Домендік таксономия 'error _ code'

• 'AUTH _' - аутентификация/авторизация.
• 'VAL _' - кіріс деректерін валидациялау.
• 'RATELIMIT _' - квоталар мен жылдамдық.
• 'IDEMP _' - сәйкестік/көшірме.
• 'CONFLICT _' - нұсқасы/күйі.
• 'DEP _' - тәуелділік (PSP/DNS/SMTP).
• 'PAY _' - төлем доменінің бизнес қателері.
• 'SEC _' - қауіпсіздік (қолтаңбалар, HMAC, mTLS).
• 'INT _' - ішкі кенеттен.

• Уақыт тұрақтылығы (back-compat).
• Қателер каталогындағы сипаттамалар мен мысалдар (docs + machine-readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• Егер 'true' - міндетті түрде 'Retry-After' (секундпен) немесе «экспоненциалды бэк-офф (1-2 с, макс. 30-60 с)» келісімшарты.

Retriable әдетте: '502/503/504', кейбір '500', '429' (терезеден кейін).
Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate limit & quota қателері (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) Теңсіздік және жанжалдар

Жазу сұрауларында - «Idempotency-Key» (24-72 сағат ішінде бірегей).
Қайталау әрекетінің қайшылығы → 409 Conflict 'error _ code: "IDEMP_REPLAY"'.
ETag → 412 Precondition Failed бойынша ресурс нұсқаларының қайшылығы.
Жауап ретінде 'resource _ id '/' status _ url' бағдарламасын қолданыңыз.

9) Валидация және 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"}
]
}

• Бизнес-валидация үшін 400 - 422 қайталамаңыз.
• Хабар - адам оқылатын; 'code' - машиналық.

10) Қателер қауіпсіздігі

Ешқашан: stack traces, SQL, файл жолдары, жеке хост аттары.
PII өңдеңіз; GDPR/DSAR.
Қолтаңба/НМАС үшін: 'SEC _ SIGNATURE _ MISMATCH' (403) және 'SEC _ TIMESTAMP _ SKEW' (401/403) дегенді «5 минутқа ± уақытты тексеріңіз» деген кеңеспен ажыратыңыз.

11) Корреляция және бақылау

Әрқашан 'trace _ id '/' X-Request-ID' қосыңыз және логин/жолдарға лақтырыңыз.
Қателерді 'error _ code' және 'status' → дашбордтар «топ-қателер», «new vs known» бойынша біріктіріңіз.
Алерталар: 5xx/422/429 өрісі, жасырындылығы p95, share of errors.

12) gRPC/GraphQL/Webhooks - маппингтер

gRPC ↔ HTTP

GraphQL

Көлік 200, бірақ 'errors []' ішінде - 'extensions' қосыңыз. code` и `trace_id`.
«Фатала» үшін (аутентификация/квота) - нақты HTTP 401/403/429 жақсы.

Webhooks

Тек 2xx алушыны табысты деп есептеңіз.
Экспоненциалды бэк-оффы бар ретраилер, 'X-Webhook-ID', 'X-Signature'.
Алушыдан 410 - ретрацияны тоқтату (endpoint жойылған).

13) Қателерді нұсқалау

'type '/' error _ code' - тұрақты; жаңасын қосу ғана.
Дене схемасын өзгерткенде - API немесе 'problem + json кіші нұсқасын көтеріңіз; v=2`.
Құжаттама: кодтар кестесі + мысалдар; changelog қателер.

14) Құжаттама (OpenAPI үзінділері)

Жаһандық жауаптар

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 }

Эндпоинт үлгісі

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) Тестілеу және сапа

Келісім-тестілер: сәйкестік 'application/problem + json', міндетті өрістер.
Negative tests: барлық тармақтары 401/403/404/ 409/422/429/500.
Chaos/latency: 5xx/ 503/504/429 ретрайлерді тексеру ('Retry-After').
Security tests: ішкі хабарламалардың болмауы, PII дұрыс маска.
Backward-compat: ескі клиенттер жаңа өрістерді түсінеді (қосыңыз, сындырмаңыз).

16) Енгізу чек-парағы

• Бірыңғай 'problem + json' + тұрақты 'error _ code'.
• HTTP/gRPC/GraphQL дұрыс семантикасы.
• Retriable/non-retriable + 'Retry-After '/бэк-офф ұсынымдары.
• Rate-limit тақырыптары және 429 мінез-құлық.
• Сәйкестілік ('Idempotency-Key', 409/412).
• Қауіпсіздік: stack traces/құпиясыз, PII редакциясы.
• 'trace _ id '/' X-Request-ID' барлық қателерде.
• Қателер каталогының құжаттамасы және мысалдар.
• Қателердің таксономиясы бойынша мониторинг.
• Теріс сценарийлердің автотестері.

17) Шағын FAQ

400-дің 422-ден айырмашылығы неде?
400 - сынған сұрау (синтаксис/мазмұн түрі). 422 - синтаксис бойынша валидті, бірақ бизнес-ережелер өтпеді.

401 қашан, ал 403 қашан?
401 - жоқ/дұрыс емес токен; 403 - токен бар, құқықтар жетіспейді.

Әрқашан 'Retry-After' керек пе?
429/503 үшін - иә; қалғандары үшін retriable - нақты ұсыныс берген дұрыс.

Жиынтығы

Жақсы жобаланған қателер - бұл келісім-шарт: дұрыс HTTP-мәртебесі, бірыңғай 'problem + json', тұрақты 'error _ code', ретрациялар бойынша айқын кеңестер және қатаң қауіпсіздік. Форматты стандарттаңыз, таксономияны құжаттаңыз, телеметрия мен тесттерді қосыңыз - және сіздің API интеграторларға болжамды, қауіпсіз және достық болады.