API սխալի և best pract.ru

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

Հաճախորդների կանխատեսելիությունը 'միասնական ձևաչափը և գետերի վարքագիծը։

Դեբագի արագացումը '«trace _ id »/« request _ id», կայուն «error _ code»։

Անվտանգություն 'չեն կարողանա արտահոսել SQL/stack traces/wings։

Դիտարկումը 'սխալների տաքսոնոմիայի հաշվետվությունները (վալիդացիա, քվոտաներ, թայմաուտներ և այլն)։

2) Հիմնական սկզբունքները

1. Բոլոր 4xx/5xx (և 2xx-ի համար մասնակի սխալներով 'առանձին սխեմա)։

2. HTTP-ի հստակ իմաստությունը 'ճիշտ կարգավիճակը ամենակարևորն է։

3. Երկու կոդի մակարդակ 'տեղափոխական («status») և հիբրիդային կայուն «error _ code»։

4. Retriable vs Non-retriable-ը ցույց է տալիս հստակ և թույլ տվեք ենթադրել back-off-ը։

5. Լռելյայն անվտանգությունը 'մանրամասները միայն հաճախորդին իրավունքների հետ։ առանց ներքին ուղու։

6. Տեղայնացումը 'մեքենայական կոդը մնում է կայուն, տեքստը թարգմանություն է։

3) Սխալների միասնական ձևաչափը (հիմնվելով RFC 78.1)

Առաջարկված JSON (ընդլայնված «applation/problem + json»)

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 []» (230 մ), «retriable», «hint», «meta»։

Վերնագրերը պատասխանում են

`Content-Type: application/problem+json`

`X-Request-ID`/`Traceparent` (W3C)

(429/503) «Retry-After» (վայրկյան կամ ամսաթիվը)

4) HTTP ստատուսների սեմանտիկան («դասականների» և պրակտիկայի միաձուլումը)

2xx (հաջողությունը նյուանսների հետ)

200 OK-ը սովորական հաջողություն է։

201 Created-ը ստեղծվել է ռեսուրս (Corpation)։

Accepted-ը ասինխրոն է հերթում (տվեք «status _ ul»)։

207 Multi-Status-ը մասնակի հաջողություն է (խուսափեք, եթե կարող եք)։

4xx (հաճախորդի սխալը)

400 Bad Request-ը սինթակսիս/ձևաչափ է, բայց ոչ դաշտերի (ավելի լավ 422)։

401 Unauthorized - ոչ/սխալ հոսանք։ Եկեք «WWW-Authenticate»։

403 Forbidden-ը թոկեն է, բայց իրավունքները բավարար չեն (RBAC/ABAC/limits)։

404 Not Found-ը ռեսուրս/endpoint բացակայում է։

409 Sylict-ը տարբերակների/վիճակի հակամարտությունն է (optimistic noking, idempotency)։

410 Gone - endpoint ընդմիշտ հանվել է։

412 Precondom Failed - ETag/If-Match չի անցել։

415 Unsupronted Media Type-ը սխալ «Content-Type» է։

422 Unprocessable Entity-ը բիզնես կանոնների առաջնորդությունն է։

429 Too Many Reques.ru - ավելի բարձր քվոտաներ/արագություն (տե՛ ս 387)։

5xx (սերվերի սխալ)

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

502 Bad Gateway-ը ապստրիմի սխալ է։

503 Windows Unavailable-ը դեգրադացիա/գերծանրքաշային, թույլ տվեք «Retry-After»։

504 Gateway Timeout-ը backend- ի թայմաուտն է։

5) Երկրորդային «error _ code» տաքսոնոմիա

Միջակայքը

«AUTH _» - վավերացում/հեղինակային։

«VAL _» -ը մուտքային տվյալների վալիդացիա է։

«RATELIMIT _» - քվոտաները և արագությունը։

«IDEMPP _» -ը դիֆերենցիալ/կրկնօրինակումներ է։

«MSLICT _» - տարբերակները/վիճակը։

«DEP _» կախվածությունը (PMS/MS/SMTP/SMTP)։

«CSO _» -ը երկրորդային տիրույթի բիզնես սխալներն են։

«SEC _» -ը անվտանգությունն է (ստորագրություններ, HMAC, mTSA)։

«INT _» -ը ներքին հանկարծակի է։

Պահանջները

Մոսկվան ժամանակի ընթացքում (back-compat)։

Նկարագրությունները և օրինակները սխալների վերլուծության մեջ (docs + machine-readable JSON)։

6) Retriable vs Non-retriable

Դաշտերը

`retriable: true|false`

Եթե <& lt> պարտադիր է 'Retry-After' (վայրկյանում) կամ պայմանագիրը «էքսպոնենցիալ back-փլեյ (սկսած 1-2 s, max 30-60 s)»։

Retriable-ը սովորաբար '«502/503/504», որոշ «500», «429» (պատուհանից հետո)։

Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate limit & www.ta սխալներ (429) (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 ժամ)։

Ռուսական վիրահատության հակամարտությունը 2449 Delict-ի հետ 'error _ code: «IDEMPP _ REPLAY»։

Ռեսուրսի տարբերակների կոնֆլիկտը ETag 24412 Precondom Failed-ով։

Պատասխանում կցեք «resource _ id »/« status _ ul» անվտանգ երկրորդ հարցման համար։

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-ին։

Ստորագրության համար/NMAS: Տարբերեք «SEC _ SIGNATURE _ MISMATCH» (403) և «SEC _ TIMESTAMP _ SKEW» (401/403) հուշումով «355 րոպե»։

11) Հարաբերակցություն և դիտողություն

Միշտ ավելացրեք «trace _ id »/« X-Request-ID» և լույսերի/հետքերի մեջ։

Սխալները համախմբեք «error _ code» և «status» -ը dashbords «լավագույն սխալները», «new vs known»։

Ալերտներ ՝ 5xx/422/429, p95 լատենտ, of errors։

12) gRPC/GraphQL/Webhooks - mapings

gRPC ↔ HTTP

GraphQL

Տեղափոխությունը 200, բայց «errors []» ներսում ավելացրեք «extensions»։ code` и `trace_id`.

«Ֆաթալի» համար (վավերացում/քվոտա) ավելի լավ է իրական HTTP 401/403/429։

Webhooks

Միայն 2xx-ը հաջողակ համարեք։

Retrai-ը էքսպոնենցիալ back-off, «X-Webhook-ID», «X-Signature»։

410 ստացողից 'կանգնեցնել retrai (endpoint հեռացված)։

13) Սխալների տարբերակումը

"Type '/" error _ code" - կայուն; նոր, միայն ավելացնել։

Երբ փոխեք մարմնի սխեման, ավելացրեք API կամ "problem + json; v=2`.

Իսպանիա: 105 104 + օրինակներ; 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) Փորձարկում և որակ

Պայմանագրային թեստերը 'համապատասխանեցնել «applation/problem + json», պարտադիր դաշտերը։

Negative tes.ru: Բոլոր ճյուղերը 401/403/404/409/422/429/500։

Chaos/latency: 5xx/503/504/429 («Retry-After»)։

Deltes.ru 'ներքին հաղորդագրությունների բացակայություն, PII ճիշտ դիմակ։

Backward-compat: Հին հաճախորդները հասկանում են նոր դաշտերը (ավելացրեք, մի կոտրեք)։

16)

• Միասնական 'problem + json' + կայուն «error _ code»։
• HTTP/gRPC/GraphQL-ի ճիշտ սեմանտիկան։
• Retriable/non-retriable + «Retry-After »/back-off առաջարկություններ։
• Rate-limit վերնագրեր և 429 վարք։
• Idempotenty («Idempotency-Key», 407/412)։
• Անվտանգություն ՝ առանց stack traces/գաղտնիքների, PII խմբագրություն։
• «trace _ id »/« X-Request-ID» բոլոր սխալներում։
• Ռուսաստանի սխալները և օրինակները։
• Սխալների տաքսոնոմիա։
• Բացասական արձագանքներ։

17) Mini-FAQ

Ինչպե՞ ս է 400-ը տարբերվում 422-ից։

400 - կոտրված հարցում (սինթակիս/պարունակության տիպ)։ 422 - վալիդային սինթակիս, բայց բիզնես կանոնները չեն անցել։

Ե՞ րբ 401, իսկ ե՞ րբ 403։

401 - ոչ/սխալ հոսանք; 403 - կա հոսանք, բավարար իրավունքներ։

Արդյո՞ ք միշտ պետք է «Retry-After»։

429/503 - այո; մյուս retriable-ի համար ցանկալի է հստակ ցուցիչ տալ։

Արդյունքը

Լավ նախագծված սխալները պայմանագիրն են 'ճիշտ HTTP կարգավիճակը, միասնական «problem + json», կայուն «error _ code», ակնհայտ ենթադրություններ հետքերով և խիստ անվտանգությամբ։ Ստանդարտացրեք ձևաչափը, վավերացրեք տաքսոնոմիան, ավելացրեք հեռուստատեսությունը և թեստերը, և ձեր API-ն կդառնա կանխատեսելի, անվտանգ և ընկերական ինտեգրատորների համար։