შეცდომების და სტატუსის კოდების დამუშავება

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

• პროგნოზირებადი დაშიფვრის პრობლემის ტიპს,
• აძლევს კლიენტს არსებულ რჩევებს (რა უნდა გააკეთოს შემდეგ),
• იცავს შიდა ნაწილების გაჟონვისგან
• თავსებადია ჭრილობებთან და იდემპოტენტურობასთან.

2) დიზაინის პრინციპები

1. შეცდომების ერთი სქემა ყველა სერვისისთვის (REST/GraphQL/gRPC/webhooks).
2. რეპრესიების მკაფიო სემანტიკა: რომელი კოდების გადატვირთვა, რომელი არა.
3. Fail-closed write ოპერაციებზე: უკეთესია 4xx/5xx, ვიდრე მშვიდი არაკონსტიტუციურობა.
4. გაჟონვის გარეშე: არ გაამჟღავნოთ SQL, მინა, კონფიგურაცია, შიდა ID.
5. კვალი: ყოველთვის დააბრუნეთ 'trace _ id '/' correlation _ id'.
6. შეტყობინებების ლოკალიზაცია არჩევითია, მაგრამ კოდი და 'reason' რჩება სტაბილური.

3) ერთიანი ფორმატი (Problem Details/JSON)

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

• 'ტიპი' - შეცდომების კლასის სტაბილური URL იდენტიფიკატორი.
• 'code' არის მოკლე მანქანების დომენის კოდი (სტაბილური გამოშვებებს შორის).
• 'hint' - რა უნდა გააკეთოს კლიენტმა (გამეორება, განაახლეთ ნიშანი, შეცვალეთ პარამეტრები).
• 'meta' - უსაფრთხო ნაწილები (საიდუმლოებების გარეშე და PII).

4) სტატუსის კოდების რუკა (მინიმალური ნაკრები)

ავთენტიფიკაცია/ავტორიზაცია

400 Bad Request არის სტრუქტურული შესაბამისობა/სქემა.
401 Unauthorized - არა/არ არის ნიშანი. დაამატეთ 'WWW-Authenticate'.
403 Forbidden არის ავთენტიფიცირებული, მაგრამ არ არსებობს უფლებები/პოლიტიკამ უარი თქვა.
404 Not Found - შენიღბეთ რესურსის არსებობა უფლებების არარსებობის შემთხვევაში.
409 Conflict - ვერსიების/სახელმწიფოების კონფლიქტი (optimistic lock, idempotence).
451 Unavailable For Legal Reasons - შესაბამისობის/იურისდიქციის ბლოკი.

ლიმიტები და დაცვა

408 Request Timeout - კლიენტი სხეულს ძალიან ნელა აგზავნის.
409/425 Too Early - ადრეული გამეორების აკრძალვა 0-RTT/TLS 1. 3.
429 Too Many Requests - ერთად „Retry-After“ და ლიმიტის პოლიტიკა.
499 Client Closed Request - (პერიმეტრზე/NGINX) კლიენტმა შეწყვიტა კავშირი.

მონაცემები და ბიზნეს წესები

422 Unprocessable Content - ბიზნესის პასუხისმგებლობამ გაიარა სქემა, მაგრამ მნიშვნელობა არასწორია.
423 Locked - რესურსი დაბლოკილია (KYC მიმოხილვა, AML freeze).
409 Conflict არის ორმაგი გაგზავნა, რბოლა, სახელმწიფო ლიმიტი (მაგალითად, „უკვე დამუშავებაში“).
410 Gone - ამოიღეს ენდოინტი/რესურსი (დეპრესია დასრულებულია).

სერვერი

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

5) Retrai და idempotence სემანტიკა

შეუძლებელია გადატვირთვა: 400/401/403/404/422 (თუ კლიენტმა არ შეცვალა მოთხოვნა).
თქვენ შეგიძლიათ დახარჯოთ: 408/429/5xx/425/499/504 (backoff + jitter- ით).
Idempotence: 'POST' - სთვის ჩართეთ 'Idempotency-Key "(UUIDv4).

409 დაუბრუნდით განმეორებით კონფლიქტს 'hint- ით: "Use same Idempotency-Key ან GET Status" ".
დაამატეთ 'Idempotency-Replay: ნამდვილი' შენახული შედეგის დაბრუნებისას.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1730641030

6) შესვლის შესაბამისობა: ველების შეცდომების სტრუქტურა

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) ნაწილობრივი მარცხი

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.
გვერდის დასასრული - 'შემდეგი _ page _ token' არ არის.
არასწორი ნიშანია 400 c 'code: PAGINATION _ CURSOR _ INVALID'.

9) Webhooks: საიმედო მიწოდება

ხელი მოაწერეთ მოვლენებს (HMAC) და შეამოწმეთ დამუშავებამდე.
წარმატებული დამუშავების პასუხი არის 2xx (უკეთესია, ვიდრე 204).
მიმღების დროებითი წარუმატებლობაა 5xx; გამგზავნი იმეორებს (ექსპონენციალური backoff, jitter).
deduplication 'event _ id' და შედეგის შენარჩუნება (idempotent consumer).
დაუშვებელი payload - 400/422 გამეორების გარეშე.

10) პროტოკოლების შესაბამისობა (gRPC/GraphQL)

• `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

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/408).
'Warning' არის რბილი დეგრადაცია ან დეპრესია („199 - Feature X არის დეპრესიული“).
`Deprecation`, `Sunset`, `Link: <...>; rel = „deprecation“ '- გათიშვისთვის.
'Problem-Type' (კასტომი) - შეცდომების სწრაფი როტინგი კლიენტზე.
'X-Trace-Id '/' Correlation-Id' - აკავშირებს logs/traces.

12) შეტყობინებების უსაფრთხოება

არ გაიმეოროთ შეყვანის საიდუმლოებები (ნიშნები/ხელმოწერები) პასუხის სხეულში.
შენიღბეთ PAN/PII ('1234').
401/403 წლისთვის - არ გაამჟღავნოთ რომელი ატრიბუტი ვერ მოხერხდა.
404 წლისთვის, „resource exists 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', 'ტიპი', 'status', 'route', 'tenant', PII გარეშე.

• ზრდა '5xx _ rate> X%' RPS> N;
• ზრდა 429 კრიტიკულ მარშრუტებზე;
• დამოკიდებულების 'timeout/504';
• ხშირი 409/idempotence არის რბოლების ნიშანი.

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,409 (იდემპოტენტურობა)

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 შეცდომები ტექსტით სხეულში.
აურიეთ სხვადასხვა შეცდომის ფორმატები მომსახურებებს შორის.
დასტის/SQL/ცხრილების სახელები/შიდა URL 'detail'.
გამოიყენეთ 'მესიჯი' სტაბილური 'კოდის '/' ტიპის' ნაცვლად.
500 დაბრუნება მოსალოდნელი ბიზნეს შეცდომით (მაგალითად, „ბალანსი არასაკმარისია“).
შეუსაბამო სემანტიკა REST/GraphQL/gRPC შორის.

16) iGaming/ფინანსების სპეციფიკა

მკაფიო კოდები KYC/AML/სანქციებისთვის: 'KYC _ REQUIRED', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTIOOOON N - ს _ B.
იურისდიქციის შეზღუდვები: 451 უსაფრთხო ფორმულირებით, სიების მითითების გარეშე.
ფულადი write ოპერაციები: 409/423 კონკურენციისა და დაბლოკვის დროს, 'hint' გამეორების ფანჯრით.
მოთამაშის ლიმიტების ინვარიანტები: გამოიყენეთ 422 პასუხისმგებელი გადახდის წესების დარღვევისთვის.
აუდიტი: უცვლელი გადაწყვეტილებების ჟურნალები (კოდი, დრო, აქტორი, trace _ id).

17) მზადყოფნის ჩეკის სია

• ერთი JSON შეცდომის სქემა, სტაბილური 'ტიპი '/' code'.
• HTTP gRPC/GraphQL შეთანხმებულია და დოკუმენტირებულია.
• Retry + 'Retry-After' სემანტიკა; იდემპოტენტურობა write- ისთვის.
• PII/საიდუმლოებების ნიღაბი; 404 რესურსების დამალვისთვის.
• შეცდომების მეტრიკა და ალერტა; კორელაცია 'trace _ id'.
• დეპრესიის პოლიტიკოსები: 'დეპრესია', 'Sunset', 'Link'.
• ტესტები: negative/fuzz, ვერსიების კონფლიქტი, დამოკიდებულების ვარდნა, ორმაგი წყალქვეშა.
• ჰაიდი მომხმარებლებისთვის: სარეზერვო ოფების მაგალითები და 409/422/429/5xx დამუშავება.

18) TL; DR

სტანდარტიზდება შეცდომების ერთიანი JSON ფორმატი c 'type '/' code '/' trace _ id', გამოიყენეთ სწორი HTTP კოდები, განასხვავეთ ვალიდაცია (400/422), უფლებები (401/403/404), კონფლიქტები/idempotence (409) და ლიმიტები (429). მოდით, მკაფიო 'Retry-After' და 'hint', შეავსეთ მგრძნობიარე მონაცემები, შეაფასეთ შეცდომები 'trace _ id- ით "და ააშენეთ ალერტები 5xx/429/p99.