Hata İşleme ve Durum Kodları

1) Hataları neden standartlaştırın

• Tahmin edilebileceği gibi, sorunun türünü kodlar,
• Müşteriye geçerli istemleri verir (daha sonra ne yapmalı),
• İç parçaların sızıntısına karşı korur,
• Retras ve idempotency ile uyumludur.

2) Tasarım ilkeleri

1. Tüm hizmetler için bir hata şeması (REST/GraphQL/gRPC/webhooks).
2. Geri çekilmelerin açık semantiği: hangi kodların geri çekileceği, hangilerinin çekilmeyeceği.
3. Yazma işlemlerinde başarısız-kapalı: sessiz tutarsızlıktan daha iyi 4xx/5xx.
4. Sızıntı yok: SQL, yığınlar, yapılandırmalar, dahili kimlikleri açıklamayın.
5. Trace - Her zaman 'trace _ id'/' correlation _ id' döndürün.
6. İletilerin yerelleştirilmesi isteğe bağlıdır, ancak kodlar ve 'reason' sabit kalır.

3) Tek format (Sorun Ayrıntıları/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' kararlı bir hata sınıfı URL'sidir.
• 'kod' - kısa etki alanı makine kodu (sürümler arasında kararlı).
• 'hint' - müşteri için ne yapmalı (tekrar et, tokeni güncelle, parametreleri değiştir).
• 'meta' - güvenli parçalar (sırlar ve PII olmadan).

4) Durum kodu haritası (minimum set)

Kimlik Doğrulama/Yetkilendirme

400 Bad Request - yapısal doğrulama/şema.
401 Yetkisiz - hayır/geçersiz belirteç. 'WWW-Authenticate' ekleyin.
403 Yasak - kimliği doğrulanmış ancak hakları/politikaları reddedilmiş.
404 Bulunamadı - hakları olmayan bir kaynağın varlığını maskeleyin.
409 Çatışma - sürüm/durum çatışması (iyimser kilit, idempotency).
451 Yasal Nedenlerle Kullanılamıyor - Uyum/Yargı Bloğu.

Sınırlar ve koruma

408 İstek Zaman Aşımı - Müşteri vücudu çok yavaş gönderiyor.
409/425 Çok Erken - 0-RTT/TLS 1'de erken tekrarın yasaklanması. 3.
429 Çok Fazla İstek - 'Retry-After've limit politikası ile.
499 İstemci Kapalı İsteği - (çevre/NGINX) istemci bağlantıyı kesti.

Veri ve İş Kuralları

422 İşlenemez İçerik - iş doğrulaması şemayı geçti, ancak anlamı yanlış.
423 Kilitli - kaynak engellendi (KYC incelemesi, AML dondurma).
409 Çatışma - çift gönderme, ırk, durum sınırı (örneğin, "zaten işlemde").
410 Gone - uç nokta/kaynak silindi (kullanımdan kaldırma tamamlandı).

Sunucu

500 Dahili Sunucu Hatası - bilinmeyen hata; Detayları açıklamıyor.
502 Bad Gateway - bağımlılık döndürülen hata/proxy oluşturma.
503 Hizmet Kullanılamıyor - bozulma/planlı çalışma; 'Retry-After' ekleyin.
504 Ağ Geçidi Zaman Aşımı.

5) Retray ve idempotency semantik

400/ 401/403/404/422'ü geri çekemezsiniz (müşteri isteği değiştirmedikçe).
Geri çekebilirsiniz: 408/429/5xx/ 425/499/504 (backoff + jitter ile).
Idempotency: 'POST' için 'Idempotency-Key' (UUIDv4) seçeneğini etkinleştirin.

Yeniden deneme çakışması için 409'u 'hitt: "Use same Idempotency-Key or GET status'ile döndürün.
Kaydedilmiş bir sonucu döndürürken 'Idempotency-Replay: true' ekleyin.

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

6) Giriş doğrulama: alan hata yapısı

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) Kısmi arızalar (toplu/kısmi arıza)

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

8) Pagination ve "boş" cevaplar

Boş koleksiyon - 200 s 'öğeleri: []', değil 404.
Sayfa sonu - 'next _ page _ token' eksik.
Yanlış belirteç - 400'lerin kodu: PAGINATION_CURSOR_INVALID'.

9) Webhooks: Güvenilir Teslimat

Olayları imzala (HMAC) ve işlemeden önce kontrol et.
Başarılı işleme yanıtı 2xx (en iyi 204).
Alıcı geçici arızalar - 5xx; Gönderen tekrar eder (üstel geri alma, jitter).
'Event _ id'ile veri tekilleştirme ve sonucu kaydetme (idempotent consumer).
Geçersiz yük - 400/422 yeniden deneme yok.

10) Protokol uygunluğu (gRPC/GraphQL)

• 'INVALID _ ARGÜMAN' - 400
• 'ONAYLANMADI' - 401
• 'PERMISSION _ DENIED' - 403
• 'NOT _ FOUND' - 404
• 'ALREADY _ EXISTS' - 409
• 'FAILED _ PRECONDITION' - 412/422
• 'RESOURCE _ BITKIN' - 429
• 'İPTAL EDİLDİ' - 409
• 'ULAŞILAMAZ' - 503
• 'DEADLINE _ EXCEEDED' - 504

json
{
"data": { "createPayment": null },
"errors": [{
"message": "Forbidden",
"extensions": { "code": "FORBIDDEN", "status": 403, "trace_id": "..." },
"path": ["createPayment"]
}]
}

Kritik hatalar için 200 yerine karşılık gelen HTTP kodunun kullanılması önerilir.

11) Başlıklar ve müşteri ipuçları

'Retry-After' - saniye/HTTP tarihi (429/503/425/408).
'Uyarı' - yumuşak bozulma veya kullanımdan kalkma ("199 - Feature X is depressed").
'Amortisman', 'Günbatımı', 'Bağlantı: <...>; rel = "amortisman" '- kontrollü kapatma için.
'Problem Tipi' (özel) - istemci üzerinde hızlı hata yönlendirme.
'X-Trace-Id'/' Correlation-Id' - günlükleri/izleri bağlar.

12) Mesaj güvenliği

Yanıt gövdesinde girdi sırlarını (belirteçleri/imzaları) tekrarlamayın.
Maske PAN/PII ('1234').
401/403 için - hangi özniteliğin başarısız olduğunu açıklamayın.
404 için, "kaynak var ama sizin değil" yerine - sadece 404.

13) Hataların gözlemlenebilirliği

• 'http _ errors _ total {durum, rota, kiracı}'
• 'error _ classes _ total {code}' (gövdeden 'kod'ile)
• Hisse 429, 5xx; Hatalı cevaplar için ayrı ayrı 'p95'/' p99' gecikme
• 'retry _ after _ seconds _ bucket' - tekrarlama ipuçlarının histogramı

• Yanıtı 'trace _ id'ile ilişkilendirir,' code ',' type ',' status ',' route ',' tenant ', PII içermez.

• RPS> N'de spike '5xx _ rate> X %';
• Kritik güzergahlarda 429 büyüme;
• bağımlılıkların 'zaman aşımı/504';
• Sık sık 409/idempotency - bir yarış işareti.

14) Örnekler

14. 1.422 (iş doğrulama)

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

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

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

Gövde hata metni ile 200 döndürün.
Hizmetler arasında farklı hata formatlarını karıştırın.
Yığın/SQL/tablo adlarını/dahili URL'leri 'detail' içinde genişletin.
Stabil 'code'/' type' yerine 'message' kullanın.
Beklenen bir iş hatası oluştuğunda 500'ü döndürün (örneğin, "bakiye yetersiz").
REST/GraphQL/gRPC arasında tutarsız semantik.

16) iGaming/Finansın Özellikleri

KYC/AML/yaptırımlar için açık kodlar: 'KYC _ REQUIRED', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
Yargı kısıtlamaları: Listeleme olmadan güvenli ifadeler ile 451.
Parasal yazma işlemleri: Rekabet ve kilitler için 409/423, bir redo penceresi ile 'ipucu'.
Oyuncu sınırı değişmezleri: Sorumlu ödeme ihlalleri için 422 kullanın.
Denetim: Değiştirilemeyen çözüm günlükleri (kod, zaman, aktör, trace_id).

17) Prod Hazırlık Kontrol Listesi

• Tek JSON hata şeması, kararlı 'tip'/' kod'.
• HTTP ↔ gRPC/GraphQL haritalama tutarlı ve belgelenmiştir.
• Retray semantiği + 'Retry-After'; Yazma için idempotency.
• PII/gizli maskeleme; 404 kaynakları gizlemek için.
• Hata ve uyarı metrikleri; 'trace _ id'ile korelasyon.
• Amortisman politikaları: 'Amortisman', 'Günbatımı', 'Bağlantı'.
• Testler: negatif/fuzz, sürüm çakışması, bağımlılık düşüşü, çift gönderme.
• Müşteri rehberi: Geri dönüş örnekleri ve 409/422/429/5xx işleme.

18) TL; DR

'Type'/' code'/' trace _ id'ile tek bir JSON hata formatını standartlaştırın, doğru HTTP kodlarını kullanın, doğrulama (400/422), (401/403/404 hakları), çakışmalar/idempotency (409) ve limitler (429) arasında ayrım yapın. Net 'Retry-After've' ipucu 'verin, hassas verileri maskeleyin,' trace _ id'ile hataları kaydedin ve 5xx/429/p99 ile uyarılar oluşturun.