API შეცდომები და საუკეთესო პრეტენზიები

1) რატომ არის შეცდომების სტანდარტიზება?

პროგნოზირება მომხმარებლებისთვის: ერთჯერადი ფორმა და ქცევა.
Debage აჩქარება: 'trace _ id '/' request _ id', სტაბილური 'error _ code'.
უსაფრთხოება: SQL/stack traces/კონფისკაცია არ გაჟღენთილია.
დაკვირვება: შეცდომების ტაქსონომიის შესახებ მოხსენებები (შესაბამისობა, კვოტები, ტაიმაუტები და ა.შ.).

2) ძირითადი პრინციპები

1. პასუხის ერთი ფორმატი 4xx/5xx (და ნაწილობრივი შეცდომებით 2xxx- ისთვის ცალკე სქემაა).
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"}
}

სავალდებულო: 'ტიპი', '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 - შეიქმნა რესურსი.
202 Accepted - ასინქრონული რიგში (მიეცით 'status _ urn').
207 Multi-Status - ნაწილობრივი წარმატება (თავიდან აიცილეთ, თუ შესაძლებელია).

4xx (კლიენტის შეცდომა)

400 Bad Request არის სინტაქსი/ფორმატი, მაგრამ არა მინდვრების შესაბამისობა (უკეთესია, ვიდრე 422).
401 Unauthorized - არა/არასწორი ნიშანი. მოდით 'WWW-Authenticate'.
403 Forbidden არის ნამდვილი ნიშანი, მაგრამ არ არის საკმარისი უფლებები (RBAC/ABAC/limites).
404 Not Found - რესურსი/endpoint არ არის.
409 Conflict არის ვერსიის/მდგომარეობის კონფლიქტი.
410 Gone - ენდოინტი სამუდამოდ ამოღებულია.
412 Precondition Failed - ETag/If-Match არ გაიარა.
415 Unsupported Media Type - არარეგულარული 'შინაარსის ტიპი'.
422 Unprocessable Entity - ბიზნესის წესების შესაბამისობა.
429 Too Many Requests - კვოტები/სიჩქარე გადააჭარბა (იხ. § 7).

5xx (სერვერის შეცდომა)

500 Internal Server Error - მოულოდნელი შეცდომა; დეტალების გამჟღავნება არ არის.
502 Bad Gateway არის აფსიდის შეცდომა.
503 სერვისი Unavailable - დეგრადაცია/გადატვირთვა, მიეცით 'Retry-After'.
504 Gateway Timeout - ზურგჩანთა.

5) დომენის ტაქსონომია 'error _ code'

• 'AUTH _' - ავთენტიფიკაცია/ავტორიზაცია.
• 'VAL _' - შეყვანის მონაცემების შესაბამისობა.
• 'RATELIMIT _' - კვოტები და სიჩქარე.
• 'IDEMP _' - idempotence/დუბლიკატები.
• 'CONFLICT _' - ვერსიები/მდგომარეობა.
• 'DEP _' - დამოკიდებულება (PSP/DNS/SMTP).
• 'PAY _' - გადახდის დომენის ბიზნეს შეცდომები.
• 'SEC _' - უსაფრთხოება (ხელმოწერები, HMAC, mTLS).
• 'INT _' - შიდა მოულოდნელი.

• სტაბილურობა დროში (უკან-კომპატი).
• შეცდომების კატალოგში აღწერილობები და მაგალითები (docs + machine readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• თუ „ნამდვილი“ - აუცილებლად 'Retry-After' (წამში) ან კონტრაქტი „ექსპონენციალური სარეზერვო ოფი (1-2 წმ-დან იწყება, მაქს 30-60 ს)“.

Retriable ჩვეულებრივ: '502/503/504', ზოგიერთი '500', '429' (ფანჯრის შემდეგ).
Non-retriable: `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
}

• `Retry-After: 12`
• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
• Для квот: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`

8) Idempotence და კონფლიქტები

ჩაწერის მოთხოვნით - '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) შეცდომების უსაფრთხოება

არასდროს: შეტევა ტრაქტები, SQL, ფაილების ბილიკები, მასპინძელთა პირადი სახელები.
რედაქტირება PII; მიჰყევით GDPR/DSAR.
ხელმოწერისთვის/NMAS: განასხვავეთ 'SEC _ SIGNATURE _ MISMATCH' (403) და 'SEC _ TIMESTAMP _ SKEW' (401/403) მითითებით: „შეამოწმეთ“ შეამოწმეთ „დრო 5 წუთი“.

11) კორელაცია და დაკვირვება

ყოველთვის დაამატეთ 'trace _ id '/' X-Request-ID "და გადაიტანეთ შეცდომები/ბილიკები.
შეცდომები გააქტიურეთ 'error _ code' და 'status' dashboards „ტოპ შეცდომები“, „ახალი შეცდომები“.
ალერტა: 5xx/422/429 სიჩქარე, ლატენტობა p95, Earrors sharl.

12) GRPC/GraphQL/Webhooks - mappings

gRPC ↔ HTTP

GraphQL

ტრანსპორტი 200, მაგრამ 'errors [] შიგნით - დაამატეთ' extensions. code` и `trace_id`.
„ფატალისთვის“ (ავთენტიფიკაცია/კვოტები) უკეთესია, ვიდრე ნამდვილი HTTP 401/403/429.

Webhooks

წარმატებულად ჩათვალეთ მხოლოდ 2xx მიმღები.
Retrai ექსპონენციალური ზურგჩანთით, 'X-Webhook-ID', 'X-Signature'.
მიმღებიდან 410 - შეჩერება (წაშლილია).

13) შეცდომების ვერსია

'ტიპი '/' error _ coded' - სტაბილური; ახლები - მხოლოდ დამატება.
სხეულის სქემის შეცვლისას - გაზარდეთ 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) ტესტირება და ხარისხი

კონტრაქტის ტესტები: შესაბამისობა 'განაცხადი/problem + json', სავალდებულო ველები.
Negative tests: ყველა ფილიალი 401/403/404/409/422/429/500.
Chaos/latence: Retry შემოწმება 5xx/503/504/429 ('Retry-After').
უსაფრთხოება: შინაგანი შეტყობინებების არარსებობა, PII სწორი ნიღაბი.
Backward compat: ძველი მომხმარებლები ესმით ახალი ველები (დაამატეთ, არ გატეხოთ).

16) განხორციელების შემოწმების სია

• ერთი 'problem + json' + სტაბილური 'error _ code'.
• სწორი სემანტიკა HTTP/gRPC/GraphQL.
• Retriable/non-retriable + 'Retry-After '/სარეზერვო რეკომენდაციები.
• სათაურები და 429 ქცევა.
• Idempotence ('Idempotency-Key', 409/412).
• უსაფრთხოება: გაფიცვის გარეშე/საიდუმლოებები, 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 გახდება პროგნოზირებადი, უსაფრთხო და მეგობრული ინტეგრატორებისთვის.