API hata kodları ve en iyi uygulamalar

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

Müşteriler için öngörülebilirlik: tek bir format ve retras davranışı.
Hata ayıklama hızlandırması: 'trace _ id'/' request _ id', kararlı 'error _ code'.
Güvenlik: SQL/stack traces/configurs sızıntı yapmaz.
Gözlemlenebilirlik: Hata taksonomisi hakkında raporlama (doğrulama, kotalar, zaman aşımları vb.).

2) Temel ilkeler

1. Tüm 4xx/5xx için tek bir yanıt biçimi (ve 2xx için kısmi hatalarla - ayrı bir şema).
2. HTTP semantiğini temizleyin: doğru durum en önemlisidir.
3. İki kod düzeyi: taşıma ('durum') ve etki alanı kararlı 'error _ code'.
4. Yeniden başlatılabilir vs Yeniden başlatılamaz: açıkça belirtin ve geri alma hakkında bir ipucu verin.
5. Varsayılan güvenlik: ayrıntılar - yalnızca hakları olan istemciye; İç izleri olmadan.
6. Yerelleştirme: makine kodu sabit kalır, metin - çeviririz.

3) Tek hata formatı (RFC 7807 tabanlı)

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

Gerekli: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
İsteğe bağlı: 'errors []' (alanlara göre), 'receivable', 'ipucu', 'meta'.

• 'Content-Type: application/problem + json'
• 'X-Request-ID'/' Traceparent' (W3C)
• (429/503 için) 'Retry-After' (saniye veya tarih)

4) HTTP durumlarının semantiği ("klasikleri've pratiği birleştirmek)

2xx (nüanslı başarı)

200 OK ortak bir başarıdır.
201 Oluşturuldu - Yer.
202 Kabul edildi - kuyrukta eşzamansız olarak ('status _ url' verin).
207 Çoklu Durum - kısmi başarı (mümkünse kaçının).

4xx (istemci hatası)

400 Bad Request - sözdizimi/format, ancak alan doğrulaması değil (tercihen 422).
401 Yetkisiz - hayır/geçersiz belirteç. Hadi 'WWW-Authenticate' yapalım.
403 Yasak - belirteç geçerlidir, ancak yeterli hak yoktur (RBAC/ABAC/limitleri).
404 Bulunamadı - kaynak/uç nokta yok.
409 Çatışma - optimal kilitleme, idempotency.
410 Gitti - uç nokta kalıcı olarak kaldırıldı.
412 Önkoşul Başarısız - ETag/If-Match başarısız oldu.
415 Desteklenmeyen Ortam Türü - Geçersiz 'İçerik Türü'.
422 İşlenemez Varlık - iş kurallarının geçerliliği.
429 Çok Fazla İstek - kotaları/hızı aştı (bkz. § 7).

5xx (sunucu hatası)

500 Dahili Sunucu Hatası - ani hata; Detayları açıklamamak.
502 Kötü Ağ Geçidi - Yukarı Akış Hatası.
503 Servis Kullanılamıyor - bozulma/aşırı yükleme, 'Retry-After' verin.
504 Gateway Timeout - arka uç zaman aşımı.

5) Etki alanı taksonomisi 'error _ code'

• 'AUTH _' - kimlik doğrulama/yetkilendirme.
• 'VAL _' - giriş verilerinin doğrulanması.
• 'RATELIMIT _' - kotalar ve hız.
• 'IDEMP _' - idempotence/kopyalar.
• 'CONFLICT _' - sürümler/durum.
• 'DEP _' - bağımlılıklar (PSP/DNS/SMTP).
• 'PAY _' - ödeme alanının iş hataları.
• 'SEC _' - güvenlik (imzalar, HMAC, mTLS).
• 'INT _' - dahili ani.

• Zaman içinde stabilite (back-compat).
• Hata dizinindeki açıklamalar ve örnekler (docs + machine-readable JSON).

6) Yeniden başlatılabilir vs Yeniden başlatılamaz

• 'tekrarlanabilir: true' felse '
• Eğer 'doğru' - mutlaka 'Retry-After' (saniye olarak) veya sözleşme "üstel geri dönüş (1-2 s'den başlayarak, maksimum 30-60 s)".

Genellikle yeniden kullanılabilir: '502/503/504', bazı '500', '429' (pencereden sonra).
Yeniden kullanılamaz: '400/401/403/404/ 409/410/415/422'.

7) Fiyat sınırı ve kota hataları (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-Kalan', 'X-RateLimit-Yeniden'
• Для квот: 'X-Kota-Sınırı', 'X-Kota-Kalan', 'X-Kota-Kalan'

8) İdempotans ve çatışmalar

Yazma taleplerinde - 'Idempotency-Key' (24-72 saat içinde benzersiz).
Çakışmayı yeniden dene> 409 'error _ code ile çakışma: "IDEMP_REPLAY"'.
ETag için kaynak sürüm çakışması - 412 Önkoşul Başarısız.
Yanıtta, güvenli bir yeniden istek için bir 'resource _ id'/' status _ url' ekleyin.

9) Doğrulama ve 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"}
]
}

• İş doğrulaması için tercih edilen 400 - 422'de aynısını çoğaltmayın.
• Mesajlar insan tarafından okunabilir; 'kod' makine tarafından okunabilir.

10) Hata güvenliği

Asla: yığın izleri, SQL, dosya yolları, özel ana bilgisayar adları.
PII'yi düzenleyin; Gözünüz GDPR/DSAR'da olsun.
İmza/HMAC için, 'SEC _ SIGNATURE _ MISMATCH' (403) ve 'SEC _ TIMESTAMP _ SKEW' (401/403) arasında "check ± time 5 min" komutu ile ayrım yapın.

11) Korelasyon ve gözlemlenebilirlik

Her zaman 'trace _ id'/' X-Request-ID' ekleyin ve günlükler/parçalar arasında ilerleyin.
Hataları 'error _ code've' status'tarafından toplayın - panolar'en üst hatalar ",'yeni vs bilinen".
Uyarılar: 5xx/422/429 spike, p95 gecikme, hata payı.

12) gRPC/GraphQL/Webhooks - eşlemeler

gRPC ↔ HTTP

GraphQL

Ulaşım 200, ama 'dehşet []' içinde - ekle 'extensions. Kod 'и' trace _ id '.
"Ölümcül" (kimlik doğrulama/kotalar) için - gerçek bir HTTP 401/403/429 daha iyidir.

Webhooks

Sadece 2xx alıcılarının başarılı olduğunu düşünün.
Üstel geri kapatma, 'X-Webhook-ID', 'X-Signature'ile Retrai.
Alıcıdan 410 - stop retray (uç nokta kaldırıldı).

13) Hata sürümü oluşturma

'type'/' error _ code' - kararlı; yeni - sadece ekle.
Gövde şemasını değiştirirken, API'nin küçük sürümünü veya 'problem + json; v = 2 '.
Belgeler: kod tablosu + örnekler; Changelog hataları.

14) Dokümantasyon (OpenAPI parçaları)

Global yanıtlar

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 }

Bir uç nokta örneği

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) Test ve kalite

Test sözleşmesi: maç 'uygulama/problem + json', gerekli alanlar.
Negatif testler: tüm dallar 401/403/404/ 409/422/429/500.
Kaos/gecikme: 5xx/ 503/504/429 ('Retry-After') için retrays denetimi.
Güvenlik testleri: dahili mesaj yok, doğru PII maskesi.
Geriye dönük compat: Eski müşteriler yeni alanları anlar (ekle, kırma).

16) Uygulama kontrol listesi

• Tek 'problem + json' + kararlı 'error _ code'.
• Doğru HTTP/gRPC/GraphQL semantiği.
• Retriable/non-retriable + 'Retry-After'/back-off önerileri.
• Hız sınırı başlıkları ve 429 davranışı.
• Idempotency ('Idempotency-Key', 409/412).
• Güvenlik: hiçbir yığın izleri/sırları, PII sürümü.
• Tüm hatalarda 'trace _ id'/' X-Request-ID'.
• Hata kataloğu belgeleri ve örnekler.
• Hata taksonomisi ile izleme.
• Olumsuz senaryoların ototestleri.

17) Mini-SSS

400'ün 422'den ne farkı var?
400 - kırık istek (sözdizimi/içerik türü). 422 - sözdiziminde geçerli, ancak iş kuralları geçmedi.

401 ne zaman ve 403 ne zaman?
401 - hayır/yanlış belirteç; 403 - bir belirteç var, yeterli hak yok.

'Retry-After'her zaman gerekli midir?
429/503 için evet; Geri kalanı için, yeniden kullanılabilir - açık bir öneri verilmesi tavsiye edilir.

Toplam

İyi tasarlanmış hatalar sözleşmedir: doğru HTTP durumu, tek 'problem + json', kararlı 'error _ code', açık retray ipuçları ve güçlü güvenlik. Formatı standartlaştırın, taksonomiyi belgeleyin, telemetri ve testler ekleyin - böylece API'niz öngörülebilir, güvenli ve entegratör dostu hale gelir.