Hatalary we status kodlaryny gaýtadan işlemek

1) Näme üçin ýalňyşlyklary standartlaşdyrmak

• meseläniň görnüşini öňünden kesgitleýär,
• müşderä hereket edýän maslahatlary berýär (indiki näme etmeli),
• içerki bölekleriň syzmagyndan goraýar,
• retralar we idempotentlik bilen gabat gelýär.

2) Dizaýn ýörelgeleri

1. Ähli hyzmatlar üçin bir ýalňyşlyk shemasy (REST/GraphQL/gRPC/webhooks).
2. Retraýlaryň aýdyň semantikasy: haýsy kodlary retraýlamak, haýsylary - ýok.
3. Write amallarynda Fil-closed: sessiz yzygiderlilige garanyňda 4xx/5xx has gowudyr.
4. Sykylyksyz: SQL, stakes, konfigi, içerki şahsyýetnamany aýan etmäň.
5. Yzarlamak: elmydama 'trace _ id '/' correlation _ id' -ni yzyna gaýtaryň.
6. Habarlaryň lokalizasiýasy - goşmaça, ýöne 'reason' kodlary durnukly galýar.

3) Ýeke-täk 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' - hata synpynyň durnukly URL şahsyýeti.
• 'code' - gysga domen kody (relizleriň arasynda durnukly).
• 'hint' - müşderi näme etmeli (gaýtalamak, belligi täzelemek, parametrleri üýtgetmek).
• 'meta' - ygtybarly jikme-jiklikler (syrsyz we PII).

4) Status kodlarynyň kartasy (iň az toplum)

Tassyklamak/ygtyýarlandyrmak

400 Bad Request - gurluş tassyklamasy/shemasy.
401 Unauthorized - no/nevaliden token. 'WWW-Authenticate' -ni goşuň.
403 Forbidden - tassyklandy, ýöne hiç hili hukuk/syýasatçy ret edildi.
404 Not Found - hukuklar bolmadyk ýagdaýynda çeşmäniň barlygyny gizläň.
409 Conflict - wersiýalaryň/ýagdaýlaryň gapma-garşylygy (optimistic lock, idempotentlik).
451 Unavailable For Legal Reasons - ylalaşyk/ýurisdiksiýa boýunça blok.

Çäkler we gorag

408 Request Timeout - Müşderi bedeni gaty haýal iberýär.
409/425 Too Early - 0-RTT/TLS ir gaýtalanmagy gadagan etmek 1. 3.
429 Too Many Requests - 'Retry-After' we çäk syýasaty bilen.
499 Client Closed Request - (perimetrde/NGINX) müşderi baglanyşygy kesdi.

Maglumatlar we işewürlik düzgünleri

422 Unprocessable Content - iş tassyklamasy shemadan geçdi, ýöne manysy nädogry.
423 Locked - çeşme petiklendi (KYC review, AML freeze).
409 Conflict - goşa iberiş, ýaryş, baýlyk çäkleri (mysal üçin, "eýýäm işlenýär").
410 Gone - endpoint/resurs aýryldy (deprekeýt tamamlandy).

Serwer

500 Internal Server Error - näbelli ýalňyşlyk; jikme-jiklikleri aýan etmäň.
502 Bad Gateway - garaşlylyk ýalňyşlygy/prokslamany yzyna gaýtardy.
503 Service Unavailable - pese gaçmak/meýilleşdirilen işler; 'Retry-After' goşuň.
504 Gateway Timeout - garaşlylyk wagty.

5) Retraýlaryň we idempotentligiň semantikasy

400/ 401/403/404/422 (eger müşderi haýyşyny üýtgetmedik bolsa).
408/429/5xx/ 425/499/504 (backoff + jitter bilen).
Idempotentlik: 'POST' üçin 'Idempotency-Key' (UUIDv4) goşuň.

Gaýtalanýan gapma-garşylyga 409 s 'hint: "Use same Idempotency-Key or GET status".
Saklanan netije yzyna gaýtarylanda 'Idempotency-Replay: true' -ni goşuň.

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

6) Giriş tassyklamasy: meýdan ýalňyşlyklarynyň gurluşy

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) Bölekleýin şowsuzlyklar (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) Paginasiýa we "boş" jogaplar

Boş kolleksiýa - 200 s 'items: []', 404 däl.
Sahypanyň soňy - 'next _ page _ token' ýok.
Nädogry belgi - 400 c 'code: PAGINATION_CURSOR_INVALID'.

9) Webhooks: ygtybarly eltip bermek

Wakalara gol çekiň (HMAC) we işlenmezden ozal barlaň.
Üstünlikli işlemäge jogap - 2xx (has gowy 204).
Alyjynyň wagtlaýyn şowsuzlyklary - 5xx; iberiji gaýtalaýar (eksponensial backoff, jitter).
'event _ id' -ni aýyrmak we netijäni saklamak (idempotent consumer).
Nädogry töleg - 400/422 gaýtalanmazdan.

10) Teswirnamalara laýyklyk (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"]
}]
}

Möhüm ýalňyşlyklar üçin 200 däl-de, degişli HTTP koduny ulanmak maslahat berilýär.

11) Müşderä sözbaşylar we maslahatlar

'Retry-After' - sekunt/NTTR-senesi (429/503/425/408).
'Warning' - ýumşak degradasiýa ýa-da deprekeýt ("199 - Feature X is deprecated").
`Deprecation`, `Sunset`, `Link: <...>; rel = "deprecation" '- dolandyrylýan öçürmek üçin.
'Problem-Type' - müşderide ýalňyşlyklaryň çalt marşrutlaşdyrylmagy.
'X-Trace-Id '/' Correlation-Id' - logleri/söwdalary birleşdirýär.

12) Habarlaryň howpsuzlygy

Jogap bedeninde giriş syrlaryny (bellikleri/gollary) gaýtalamaň.
PAN/PII ('1234').
401/403 üçin - haýsy häsiýetiň şowsuzdygyny aýtmaň.
404 üçin "resource exists but not yours" ýerine - diňe 404.

13) Ýalňyşlyklaryň syn edilmegi

• `http_errors_total{status, route, tenant}`
• 'error _ classes _ total {code}' ('code' bedenden)
• paýy 429, 5xx; 'p95 '/' p99' latency ýalňyş jogaplar üçin aýratyn
• 'retry _ after _ seconds _ bucket' - gaýtalanmalar boýunça maslahatlaryň gistogrammasy

• 'trace _ id' bilen habarlaşyň, 'code', 'type', 'status', 'route', 'tenant', PII-siz saklaň.

• sıçrama '5xx _ rate> X%' RPS> N-de;
• möhüm ugurlarda 429 ösüş;
• 'timeout/504' garaşlylyk;
• ýygy-ýygydan 409/idempotentlik → ýaryşlaryň alamaty.

14) Mysallar

14. 1 422 (iş-tassyklama)

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 (çäkler)

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

200 belgisini bedende hatanyň teksti bilen yzyna gaýtaryň.
Hyzmatlaryň arasynda dürli ýalňyşlyk formatlaryny garyşdyrmak.
/ SQL/Tablisa atlaryny/Içerki URL-leri 'detail' -de aç.
Durağan 'code '/' type' ýerine 'message' ulanyň.
Garaşylýan iş ýalňyşlygynda 500 yzyna gaýtarmak (mysal üçin, "balans ýeterlik däl").
REST/GraphQL/gRPC arasynda gabat gelmeýän semantika.

16) iGaming/Maliýe aýratynlyklary

KYC/AML/sanksiýalar üçin anyk kodlar: 'KYC _ REQUIRED', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
Ýurisdiksiýalaryň çäklendirilmegi: 451 sanawlary görkezmezden howpsuz düzülen.
Pul write-amallary: 409/423 bäsdeşlik we blokirlemelerde, "hint" gaýtalama penjiresi bilen.
Oýunçynyň çäkleriniň üýtgemegi: jogapkärli tölegleriň düzgünlerini bozmak üçin 422 ulanyň.
Audit: çözgütleriň üýtgemeýän žurnallary (kod, wagt, aktýor, trace_id).

17) Prod-taýynlyk çek-sanawy

• Bitewi JSON hatalar shemasy, durnukly 'type '/' code'.
• HTTP gRPC/GraphQL mapping tassyklandy we resminamalaşdyryldy.
• Retraýlaryň semantikasy + 'Retry-After'; write üçin idempotentlik.
• PII/syrlary gizlemek; 404 serişdeleri gizlemek üçin.
• Ýalňyşlyklaryň metrikleri we töwekgelçilikler; 'trace _ id'.
• Akym syýasaty: 'Deprecation', 'Sunset', 'Link'.
• Synaglar: negative/fuzz, wersiýalaryň gapma-garşylygy, endikleriň azalmagy, double-submit.
• Müşderilere ýol: 409/422/429/5xx arka off we gaýtadan işlemek mysallary.

18) TL; DR

c 'type '/' code '/' trace _ id' ýalňyşlyklarynyň ýeke-täk JSON formatyny standartlaşdyryň, dogry HTTP kodlaryny ulanyň, tassyklamany (400/422), (401/403/404 hukuklaryny), gapma-garşylyklary/idempotentligi (409) we çäkleri (429) tapawutlandyryň. Aýdyň 'Retry-After' we 'hint' geliň, duýgur maglumatlary gizläň, 'trace _ id' bilen ýalňyşlyklary ýazyň we 5xx/429/p99-dan alertleri guruň.