Սխալների և կանոնների վերամշակումը

1) Ինչո՞ ւ ստանդարտացնել սխալները

Սխալների միասնական պայմանագիրը արագացնում է հաճախորդների կարգաբերումը, նվազեցնում կեղծ հետքերը և դարձնում RCA վերարտադրելի։ Լավ համակարգ

կանխատեսելիորեն կոդավորում է խնդրի տեսակը,

հաճախորդին տալիս է գործող հուշումներ (ինչ անել հաջորդը),

պաշտպանում է ներքին մասերի արտահոսքից,

համատեղելի է ելույթների և գաղափարախոսության հետ։

2) Դիզայնի սկզբունքները

1. Սխալների մեկ սխալը բոլոր ծառայությունների համար (REST/GraphQL/gRPC/webhooks)։

2. Գետերի հստակ սեմանտիկան այն է, թե ինչ նպատակներով կարելի է կտրել, ինչ - որ բան ՝ ոչ։

3. Fail-closed-ը write վիրահատություններում 'ավելի լավ, քան 4xx/5xx-ը, քան հանգիստ նեկոնսիստենտությունը։

4. Առանց արտահոսքի 'մի բացեք SQL, ապակիներ, դելիգներ, ներքին ID։

5. Ուղեգիր 'միշտ վերադարձրեք «trace _ id »/« wwww.relation _ id»։

6. Հաղորդագրությունների տեղայնացումը օբյեկտիվ է, բայց կոդավորումը և «reason» մնում են կայուն։

3) Միասնական ձևաչափը (Problem Details/JSON)

Առաջարկվող հիմնական ձևաչափը (համատեղելի RFC 78.1)

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-210-ն է։

«code» -ը տիրույթի կարճ մեքենայական կոդն է (արտադրությունների միջև ֆոսֆիլեն)։

"hint '- ինչ անել հաճախորդին (կրկնօրինակը, նորարարությունը, պարամետրերը փոխելը)։

meta '- անվտանգ մանրամասներ (առանց գաղտնիքների և PII)։

4) Համապատասխան ստատուսի քարտեզը (նվազագույն հավաքածու)

Վավերացում/հեղինակային

400 Bad Request-ը կառուցվածքային վալիդացիա/սխեմա է։

401 Unauthorized - ոչ/անվանական հոսանք։ Ավելացրեք «WWW-Authenticate»։

403 Forbidden-ը վավերացված է, բայց ոչ ճիշտ/քաղաքականություն հրաժարվեց։

404 Not Found-ը դիմակավորում է ռեսուրսի գոյությունը իրավունքների բացակայության դեպքում։

409 Sylict-ը տարբերակների/պետությունների հակամարտությունն է (optimistic prok, idempotenty)։

451 Unavailable For Legal Reasons-ը կոմունիստական/իրավասության բլոկն է։

Լիմիտներ և պաշտպանություն

4.1 Request Timeout - հաճախորդը չափազանց դանդաղ ուղարկում է մարմինը։

407/425 Too Early - վաղ խոհարարի արգելքը 0-RTT/TMS 1։ 3.

429 Too Many Reques.ru - «Retry-After» և լիմիտի քաղաքականությունը։

249 Client Closed Request-ը (պարագծի/NGINX) հաճախորդը կոտրեց կապը։

Տվյալները և բիզնես կանոնները

422 Unprocessable Content-ը բիզնես վալիդացիան անցավ սխեմա, բայց իմաստը սխալ է։

423 Noked-ը արգելափակված է (KYC review, AML freeze)։

409 Sylict - կրկնակի ուղարկում, մրցավազք, վիճակի սահմանափակում (օրինակ ՝ «արդեն վերամշակման մեջ»)։

410 Gone - endpoint/ռեսուրսը հեռացված է (դեպրեսիտը ավարտվել է)։

Սերվերը

500 Server Error-ը անհայտ սխալ է։ մի բացահայտեք մանրամասները։

502 Bad Gateway - կախվածությունը վերադարձրեց սխալը/սայթաքումը։

503 Express Unavailable - դեգրադացիա/պլանավորված աշխատանք; ավելացնել 'Retry-After'։

504 Gateway Timeout-ը կախվածության թայմաուտ է։

💡 Կանոն 'write վիրահատություններ, երբ կասկածում են 4.9 (հակամարտություն) կամ 503 (ավելի ուշ), ոչ թե 200։

5) Ռեթերի և կուռքերի սեմանտիկան

Դուք չեք կարող կտրել '400/401/403/404/422 (եթե հաճախորդը չի փոխել հարցումը)։

Դուք կարող եք կտրել ՝ 407/429/5xx/425/425/499/504 (backoff + jitter)։

«POST» -ի համար ներառեք «Idempotency-Key» (UUIDv4)։

Կրկին կատարման հակամարտությանը վերադարձրեք 407-ից '«Use same Idempotency-Key or GET status»։

Ավելացրեք 'Idempotency-Replay: 108' պահպանված արդյունքը վերադարձնելիս։

Headers-ի օրինակ 429-ում


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)

Batch-endpoints-ում մի թաքցրեք սխալները 200-ի ներսում առանց կառուցվածքի։ Վերադարձեք 207 Multi-Status կամ 200 C արդյունքների զանգվածով, որտեղ յուրաքանչյուր առաջադրանք ունի իր կարգավիճակը

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 _ III ALID "։

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» - վայրկյաններ/NTTR-ամսաթիվը (429/503/425/407)։

«Warning» -ը փափուկ դեգրադացիաներ կամ դեպրեսեյթ է («199-Feature X is deprecated»)։

`Deprecation`, `Sunset`, `Link: <...>; rel = «deprecation» - վերահսկվող ինտեգրման համար։

«Problem-Type» (կաստոմային) - արագ սխալների ռոտինգը կլիենտում։

"X-Trace-Id '/" Eurelation-Id" -ը կապում է լոգերը/թրեյզերը։

12) Հաղորդագրությունների անվտանգությունը

Մի կրկնեք մուտքային գաղտնիքները (գաղտնիքները/ստորագրությունները) պատասխանների մարմնում։

Դիմակավորված PAN/PII («1234»)։

401/403 համար մի բացահայտեք, թե որն է ձախողվել։

404-ի համար «resource exis.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», «rope», «tenae», առանց PII։

Ալերտա

աճը '5xx _ rate> X%' RPS> N;

429 աճը կրիտիկական երթուղիներում;

«timeout/504» կախվածության մեջ;

հաճախակի 407/idempotenty-ը մրցավազքի նշան է։

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 407 (idempotention)


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 վերադարձնել մարմնի մեջ սխալների տեքստով։

Խառնել տարբեր ռուսական սխալներ ծառայությունների միջև։

Բացել stek/SQL/աղյուսակների անունները/ներքին URL-ը «detail» -ում։

Օգտագործել «www.d.» 'կայուն «code »/« type» -ի փոխարեն։

500 վերադարձնել ակնկալվող բիզնես սխալի դեպքում (օրինակ, «հավասարակշռությունը բավարար չէ»)։

REST/GraphQL/gRaphQL/gRPC-ի միջև։

16) iGaming/ֆինանսական առանձնահատկությունները

KYC/AML/2019: «KYC _ REQUIRED», «KYC _ REVIEW», «AML _ MSK», «SANCTION _ BLOCKED»։

Միգրացիայի սահմանափակումները ՝ 451 անվտանգ ձևակերպմամբ առանց ցուցակների նշելու։

Դրամական write վիրահատությունները ՝ 407/423 մրցակցության և արգելափակման ժամանակ, «hint» 'խոհարարի պատուհանի հետ։

Խաղացողի լիմիտների ինվարանտները 'օգտագործեք 422-ը վճարման կանոնների խախտման համար։

Աուդիտ 'անփոփոխ լուծումների ամսագրեր (կոդ, ժամանակ, ակտոր, թրace _ id)։

17) Չեկ-թուղթ պատրաստակամության համար

Միասնական JSON սխալի սխալը, կայուն «type »/« code»։
Mapping HTTP www.gRPC/GraphQL-ը համաձայնեցված է և տեղադրված է։
Retry-After '; write-ի համար։
PII/գաղտնիքների դիմակավորում; 404 ռեսուրսների թաքցնելու համար։
Սխալներ և ալտերտեր; կորլացիա '«trace _ id»։
Դեպրեսիտի քաղաքականությունը '«Deprecation», «Sunset», «Link»։
Թեստեր ՝ negative/fuzz, տարբերակների հակամարտություն, կախվածության նվազում, double-intertit։
Disd հաճախորդներին 'back-off-ի օրինակներ և 4.9/422/429/5xx վերամշակում։

18) TL; DR

Ստանդարտացրեք մեկ JSON-ձևաչափը '«type »/« code »/« trace _ id», օգտագործեք ճիշտ HTTP-կոդերը, տարբերեք վալիդացիան (400/422), իրավունքները (401/403/404), կոնֆլիկտները/idempotention (407) և limits (429)։ Եկեք պարզ «Retry-After» և «hint», դիմեք զգայուն տվյալներին, տրամաբանեք սխալները «trace _ id» -ից և կառուցեք ալտերտեր 5xx/429/p99։