Səhv emalı və status kodları

1) Niyə səhvləri standartlaşdırmaq

• problemin növünü proqnozlaşdırıla bilən şəkildə kodlaşdırır,
• müştəriyə mövcud ipuçları verir (bundan sonra nə etmək lazımdır),
• daxili hissələrin sızmasından qoruyur,
• retras və idempotentlik ilə uyğundur.

2) Dizayn prinsipləri

1. Bütün xidmətlər üçün bir səhv sxemi (REST/GraphQL/gRPC/webhooks).
2. Retrayaların aydın semantikası: hansı kodları retraye etmək, hansı - yoxdur.
3. Write əməliyyatlarında fail-closed: 4xx/5xx səssiz qeyri-sabitlikdən daha yaxşıdır.
4. Sızma yoxdur: SQL, yığınları, konfiqləri, daxili şəxsiyyətləri açıqlamayın.
5. Tracking: həmişə 'trace _ id '/' correlation _ id' qaytarın.
6. Mesajların lokallaşdırılması - isteğe bağlıdır, lakin 'reason' kodları sabit qalır.

3) Vahid format (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"
}
}

• 'type' - sabit səhv sinif URL identifikatorudur.
• 'code' - qısa domen kodu (buraxılışlar arasında sabitdir).
• 'hint' - müştəriyə nə etmək (təkrarlamaq, tokeni yeniləmək, parametrləri dəyişdirmək).
• 'meta' - təhlükəsiz detallar (sirr və PII olmadan).

4) Status kodları xəritəsi (minimum dəsti)

Autentifikasiya/avtorizasiya

400 Bad Request - struktur validasiya/sxem.
401 Unauthorized - No/nevaliden token. 'WWW-Authenticate' əlavə edin.
403 Forbidden - təsdiq, lakin heç bir hüquq/siyasətçilər imtina.
404 Not Found - Hüquqlar olmadıqda resursun mövcudluğunu maskalayın.
409 Conflict - versiyalar/hallar toqquşması (optimistic lock, idempotent).
451 Unavailable For Legal Reasons - komplayens/yurisdiksiya bloku.

Limitlər və qorunma

408 Request Timeout - müştəri cəsədi çox yavaş göndərir.
409/425 Too Early - 0-RTT/TLS 1-də erkən təkrarlama qadağası. 3.
429 Too Many Requests - «Retry-After» və limit siyasəti ilə.
499 Client Closed Request - (perimetrdə/NGINX) müştəri əlaqəni kəsdi.

Məlumat və biznes qaydaları

422 Unprocessable Content - Biznes validasiya sxemi keçdi, lakin mənası yanlışdır.
423 Locked - resurs bloklanır (KYC review, AML freeze).
409 Conflict - ikiqat göndərmə, yarış, vəziyyət limiti (məsələn, «artıq emal olunur»).
410 Gone - end point/resurs silindi (deprequeit tamamlandı).

Server

500 Internal Server Error - naməlum səhv; detalları açıqlamayın.
502 Bad Gateway - asılılıq səhv/proksasiya qaytardı.
503 Service Unavailable - deqradasiya/planlı iş; əlavə edin 'Retry-After'.
504 Gateway Timeout - asılılıq müddəti.

5) Retraj və idempotentlik semantikası

400/ 401/403/404/422 (müştəri sorğunu dəyişdirməyibsə).
408/429/5xx/ 425/499/504 (backoff + jitter ilə).
İdempotentlik: 'POST' üçün 'Idempotency-Key' (UUIDv4) daxil edin.

Təkrar icra konfliktinə 409 s 'hint' qaytarın: «Use same Idempotency-Key or GET status».
Saxlanılan nəticəni geri qaytararkən 'Idempotency-Replay: true' əlavə edin.

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

6) Giriş validasiyası: sahə səhvlərinin strukturu

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) Qismən uğursuzluqlar (batch/partial failure)

json
{
"status": "partial",
"succeeded": 8,
"failed": 2,
"results": [
{"id": "op1", "status": 201},
{"id": "op2", "status": 422, "error": {"code":"VALIDATION_ERROR","detail":"..."}}
]
}

8) Paginasiya və «boş» cavablar

Boş kolleksiya - 200 s 'items: []', 404 deyil.
Səhifənin sonu - 'next _ page _ token' yoxdur.
Səhv token - 400 c 'code: PAGINATION_CURSOR_INVALID'.

9) Webhooks: etibarlı çatdırılma

Hadisələri (HMAC) imzalayın və emaldan əvvəl yoxlayın.
Uğurlu emala cavab - 2xx (daha yaxşı 204).
Alıcının müvəqqəti uğursuzluqları - 5xx; göndərici təkrar edir (eksponensial backoff, jitter).
'event _ id' deduplikasiyası və nəticənin saxlanması (idempotent consumer).
Səhv payload - 400/422 təkrarsız.

10) Protokollara uyğunluq (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"]
}]
}

Kritik səhvlər üçün 200 deyil, müvafiq HTTP kodunu istifadə etmək tövsiyə olunur.

11) Müştəri başlıqları və ipuçları

'Retry-After' - saniyə/NTTR-tarix (429/503/425/408).
'Warning' - yumşaq deqradasiya və ya deprekeyt («199 - Feature X is deprecated»).
`Deprecation`, `Sunset`, `Link: <...>; rel = «deprecation» '- idarə olunan kəsilmə üçün.
'Problem-Type' (xüsusi) - müştəridə səhvlərin sürətli marşrutlaşdırılması.
'X-Trace-Id '/' Correlation-Id' - qeydləri/treysləri birləşdirir.

12) Mesajların təhlükəsizliyi

Cavab orqanında giriş sirlərini (nişanlar/imzalar) təkrarlamayın.
PAN/PII ('1234') maskası.
401/403 üçün - hansı atributun uğursuz olduğunu açıqlamayın.
404 üçün «resource exists but not yours» əvəzinə - yalnız 404.

13) Səhvlərin müşahidə edilməsi

• `http_errors_total{status, route, tenant}`
• 'error _ classes _ total {code}' ('code' üçün)
• pay 429, 5xx; 'p95 '/' p99' latency ayrı-ayrılıqda səhv cavablar üçün
• 'retry _ after _ seconds _ bucket' - təkrar məsləhətlər histoqramı

• 'trace _ id' ilə əlaqə saxlayın, 'code', 'type', 'status', 'route', 'tenant', PII olmadan saxlayın.

• sıçrayış '5xx _ rate> X%' RPS ilə> N;
• kritik marşrutlarda 429 artım;
• 'timeout/504' asılılıq;
• tez-tez 409/idempotentlik → yarış əlaməti.

14) Nümunələr

14. 1 422 (biznes-validasiya)

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 (idempotentlik)

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 (limitlər)

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) Antipattern

200 bədən səhv mətni ilə geri.
Xidmətlər arasında müxtəlif səhv formatlarını qarışdırın.
Yığını/SQL/cədvəl adlarını/daxili URL-ləri 'detail' -də açmaq.
Sabit 'code '/' type' əvəzinə 'message' istifadə edin.
Gözlənilən iş səhvində 500 qaytarmaq (məsələn, «balans kifayət deyil»).
REST/GraphQL/gRPC arasında uyğunsuz semantika.

16) iGaming/Maliyyə Xüsusiyyətləri

KYC/AML/sanksiyalar üçün aydın kodlar: 'KYC _ REQUIRED', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
Yurisdiksiya məhdudiyyətləri: 451 siyahıları göstərilmədən təhlükəsiz ifadə ilə.
Pul write əməliyyatları: 409/423 rəqabət və bloklama, 'hint' təkrar pəncərə ilə.
Oyunçu limitlərinin invariantları: məsuliyyətli ödəniş qaydalarını pozmaq üçün 422 istifadə edin.
Audit: dəyişməz həll jurnalları (kod, vaxt, aktyor, trace_id).

17) Prod hazırlıq yoxlama siyahısı

• Vahid JSON səhv sxemi, sabit 'type '/' code'.
• Mapping HTTP gRPC/GraphQL razılaşdırılmış və sənədləşdirilmişdir.
• Retray semantikası + 'Retry-After'; write üçün idempotentlik.
• PII/sirlərin maskalanması; 404 resursları gizlətmək üçün.
• Səhvlərin metrikası və həyəcan; 'trace _ id' ilə korelasiya.
• Deprekeyt siyasəti: 'Deprecation', 'Sunset', 'Link'.
• Testlər: negative/fuzz, versiyalar toqquşması, asılılıq azalması, double-submit.
• Müştərilərə bələdçi: back-off nümunələri və 409/422/429/5xx emalı.

18) TL; DR

c 'type '/' code '/' trace _ id' səhvlərinin vahid JSON formatını standartlaşdırın, düzgün HTTP kodlarından istifadə edin, validasiya (400/422), (401/403/404 hüquqları), münaqişələr/idempotentlik (409) və limitlər (429) fərqləndirin. Dəqiq 'Retry-After' və 'hint' verin, həssas məlumatları maskalayın, 'trace _ id' ilə səhvləri loqolun və 5xx/429/p99-da qərəzli olun.