Рамзҳои хатогии API ва таҷрибаи пешқадам

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

Пешгӯӣ барои муштариён: формати ягона ва рафтори ретрас.
Шитоби ислоҳи хатоҳо: 'trace _ id '/' request _ id', устувор 'хатогӣ _ код'.
Амният: Пайҳо/конфигуратсияҳои SQL/stack ихроҷ намешаванд.
Мушоҳида: ҳисобот дар бораи таксономияи хатогӣ (санҷиш, квота, танаффус ва ғайра).

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

1. Формати ягонаи посух барои ҳама 4xx/5xx (ва барои 2xx бо хатогиҳои қисман - нақшаи алоҳида).
2. Семантикаи HTTP тоза кунед: мақоми дуруст муҳимтарин аст.
3. Ду сатҳи рамз: нақлиёт ('статус') ва домени устувор 'хатогӣ _ код'.
4. Retriable vs 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', 'хатогӣ _ код', 'trace _ id'.
Ихтиёрӣ: 'хатогиҳо []' (аз рӯи майдонҳо), 'бозгардонидан', 'ишора', 'мета'.

• 'Намуди мундариҷа: барнома/мушкилот + json'
• 'X-Request-ID '/' Traceparent' (W3C)
• (барои 429/503) 'Retry-After' (сония ё сана)

4) Семантикаи статусҳои HTTP (якҷоя кардани "классикӣ" ва амалия)

2xx (муваффақияти нозук)

200 OK муваффақияти муштарак аст.
201 Офарида - макон.
202 Қабул карда шуд - асинхронӣ дар навбат (додани 'status _ url').
207 Multi-Status - муваффақияти қисман (агар имкон бошад, пешгирӣ кунед).

4xx (хатои муштарӣ)

400 Дархости бад - синтаксис/формат, аммо тасдиқи майдон (беҳтараш 422).

401 беиҷозат - аломати беэътибор. Биёед 'WWW-Аутентификатсия кунем.'

403 мамнӯъ - нишона эътибор дорад, аммо ҳуқуқҳои кофӣ вуҷуд надоранд (RBAC/ABAC/маҳдудиятҳо).
404 Ёфт нашуд - манбаъ/нуқтаи ниҳоӣ нест.
409 Низоъ - қулфи оптималӣ, аблаҳӣ.
410 Gone - нуқтаи ниҳоӣ ба таври доимӣ хориҷ карда шуд.
412 Хатогии пешакӣ - ET bag/If-Match ноком шуд.
415 Намуди ВАО-и дастгирӣнашаванда - 'Намуди мундариҷа'.
422 Субъекти бебозгашт - тасдиқи қоидаҳои тиҷорат.
429 Дархостҳои аз ҳад зиёд - аз квота/суръат зиёдтар (ниг. § 7).

5xx (хатои сервер)

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

5) Домени таксономия 'хато _ рамз'

• 'AUTH _' - аутентификатсия/авторизатсия.
• 'VAL _' - тасдиқи маълумоти вуруд.
• 'RATELIMIT _' - квотаҳо ва суръат.
• 'IDEMP _' - idempotence/такрорӣ.
• 'НИЗОЪ _' - версияҳо/ҳолат.
• 'DEP _' - вобастагӣ (PSP/DNS/SMTP).
• 'PAY _' - хатогиҳои тиҷоратии домени пардохт.
• 'SEC _' - амният (имзоҳо, HMAC, MTLS).
• 'INT _' - ногаҳон дохилӣ.

• Устуворӣ бо мурури замон (back-compat).
• Тасвирҳо ва намунаҳо дар феҳристи хатогӣ (ҳуҷҷатҳо + JSON-и хонданашаванда).

6) Retriable vs Non-retriable

• 'retriable: ҳақиқӣ' false '
• Агар "дуруст" - ҳатман "Retry-After" (бо сонияҳо) ё шартнома "бозгашти экспоненсиалӣ (аз 1-2 с, макс 30-60 с)".

Одатан қобили қабул аст: '502/503/504', баъзе '500', '429' (пас аз тиреза).
Интиқолнашаванда: '400/401/403/404/ 409/410/415/422'.

7) Хатогиҳои меъёри & квота (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
}

• 'Бозсозӣ: 12'
• 'Х-Меъёри Лимит-Лимит', 'X-Меъёри Лимити-боқимонда', 'X-Rate-Limit-Reset'
• Для квот: 'X-квота-лимит', 'X-квота-боқимонда', 'X-квота-барқароркунӣ'

8) Идемпотентсия ва низоъҳо

Дар дархостҳои хаттӣ - 'Idempotency-Key' (беназир дар давоми 24-72 соат).
Низоъро такрор кунед → 409 Низоъ бо 'error _ code: "IDEMP_REPLAY"'.
Ихтилофи версияи захираҳо барои ET to 412 Precondition ноком шуд.
Дар посух, a '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, ки барои тасдиқи тиҷорат бартарӣ доранд, такрор накунед.
• Паёмҳо барои инсон қобили хондан мебошанд; 'код' қобили хондан аст.

10) Амнияти хато

Ҳеҷ гоҳ: пайгирии анборҳо, SQL, роҳҳои файл, номҳои мизбони хусусӣ.
Таҳрири PII; ба GDPR/DSAR нигоҳ кунед.
Барои имзо/HMAC, байни 'SEC _ SIGNATURE _ MISMATCH' (403) ва 'SEC _ TIMESTAMP _ SKEW' (401/403) бо дархости "вақти 5 дақиқа санҷед" фарқ кунед.

11) Таносуб ва мушоҳида

Ҳамеша 'trace _ id '/' X-Request-ID' -ро илова кунед ва тавассути гузоришҳо/роҳҳо ҳаракат кунед.
Хатогиҳои ҷамъбастии 'error _ code' and 'status' → панели панели "хатогиҳои болоӣ", "нав против маълум".
Огоҳӣ: 5xx/422/429 хӯша, p95 дермонӣ, ҳиссаи хатогиҳо.

12) GRPC/GraphL/Webhooks - харитасозӣ

GRPC ↔ HTTP

Диаграммаи QL

Интиқол 200, аммо 'хатогиҳо []' дар дохили - изофаи изофӣ. рамзи 'i' trace _ id '.
Барои "марговар" (аутентификатсия/квота) - як HTTP воқеӣ беҳтар аст.

Webhooks

Танҳо 2xx гирандаро бомуваффақият баррасӣ кунед.
Retrai бо бозгашти экспоненсиалӣ, 'X-Webhook-ID', 'X-Signature'.
410 аз қабулкунанда - бозпас гирифтани таваққуф (нуқтаи ниҳоӣ хориҷ карда шудааст).

13) Таҳрири хатогӣ

'type '/' хатогӣ _ код' - устувор; нав - танҳо илова кунед.
Ҳангоми тағир додани схемаи бадан, версияи ночизи API ё 'мушкилот + json; v = 2 '.
Ҳуҷҷатгузорӣ: ҷадвали рамз + намунаҳо; хатогиҳои changelog.

14) Ҳуҷҷатгузорӣ (Порчаҳои кушодаи API)

Ҷавобҳои глобалӣ

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) Озмоиш ва сифат

Шартномаи санҷишӣ: мувофиқати 'ариза/мушкилот + json', майдонҳои зарурӣ.
Санҷишҳои манфӣ: ҳамаи шохаҳо 401/403/404/ 409/422/429/500.
Бесарусомонӣ/таъхир: тафтиши ретрейҳо барои 5xx/ 503/504/429 ('Retry-After').
Санҷишҳои амниятӣ: ҳеҷ паёмҳои дохилӣ, ниқоби дурусти PII.
Қафо-муқоиса: Мизоҷони кӯҳна майдонҳои навро мефаҳманд (илова кунед, шикаста нашавед).

16) Рӯйхати санҷиши амалисозӣ

• Ягона 'мушкилот + json' + устувор 'хатогӣ _ код'.
• Семантикаи дурусти HTTP/g
• Тавсияҳои қобили қабул/интиқолнашаванда + 'Retry-After '/бозгашт.
• Сарлавҳаҳои маҳдудият ва рафтори 429.
• Idempotency ('Idempotency-Key', 409/412).
• Амният: пайгирӣ/асрори анбор, нашри PII.
• 'trace _ id '/' X-Request-ID' дар ҳама хатогиҳо.
• Ҳуҷҷатҳо ва намунаҳои каталоги хато.
• Мониторинг бо хатогии таксономия.
• Автотестҳои сенарияҳои манфӣ.

17) Мини-FAQ

400 аз 422 чӣ фарқ дорад?
400 - дархости шикаста (навъи синтаксис/мундариҷа). 422 - дар синтаксис эътибор дорад, аммо қоидаҳои тиҷорат нагузаштанд.

401 кай ва 403 кай аст?
401 - аломати нодуруст/нодуруст; 403 - нишонае ҳаст, ҳуқуқҳои кофӣ нестанд.

Оё 'Retry-After' always лозим аст?
Барои 429/503, бале; барои боқимонда, бозгардонидан - тавсия дода мешавад, ки тавсияи возеҳ дода шавад.

Ҷамъ

Хатогиҳои хуб тарҳрезишуда шартнома мебошанд: ҳолати дурусти HTTP, ягона 'мушкилот + json', устувории 'хатогӣ _ код', маслиҳатҳои дақиқ ва амнияти қавӣ. Форматро стандартӣ кунед, таксономияро ҳуҷҷатгузорӣ кунед, телеметрия ва санҷишҳоро илова кунед - ва API-и шумо пешгӯишаванда, бехатар ва интегратор мегардад.