Hangi HTTP Durum Kodunu Kullanmalıyım? Karar Kılavuzu

Karar Ağacı

Buradan başlayın ve durumunuza uyan yolu izleyin.

İstek başarılı oldu mu?

Evet ve veri döndürüyorum -> 200 OK Varsayılan başarı yanıtı. Veri döndüren GET istekleri, eylem gerçekleştiren POST istekleri ve sonucu güncelleyip döndüren PUT/PATCH istekleri için kullanın.

Evet ve yeni bir kaynak oluşturdum -> 201 Created POST veya PUT yeni bir şey oluşturduktan sonra kullanın. Yeni kaynağın URL’si ile bir Location başlığı ekleyin.

Evet ancak döndürülecek gövde yok -> 204 No Content Başarılı DELETE istekleri veya istemcinin güncellenmiş kaynağa ihtiyacı olmadığı PUT/PATCH için kullanın. Yanıtın gövdesi yoktur.

Evet ancak bunu zaten yaptım -> 200 OK veya 204 No Content Kaç kez çağrıldığına bakılmaksızın son durumun aynı olduğu idempotent işlemler (PUT, DELETE) için, ilk çağrıda döndüreceğiniz aynı başarı kodunu döndürün.

Kabul edildi ancak henüz bitmedi -> 202 Accepted Sunucu isteği eşzamansız işleme için kuyruğa aldığında kullanın. İstemci daha sonra yoklamalı veya bir geri arama almalıdır. Uzun süren işler, toplu işlemler veya webhook teslimatları için iyidir.

İstemcinin başka bir yere gitmesi gerekiyor mu?

Kalıcı olarak taşındı -> 301 Moved Permanently Kaynağın kalıcı olarak yeni bir URL’si var. Tarayıcılar ve arama motorları kayıtlarını günceller. GET istekleri için güvenlidir. Not: bazı eski istemciler yönlendirmede POST’u GET’e değiştirir.

Kalıcı olarak taşındı, yöntemi koru -> 308 Permanent Redirect 301 gibi, ancak HTTP yönteminin korunmasını garanti eder. Bir POST, POST olarak kalır. Yöntem korumanın önemli olduğu durumlarda kullanın (API yönlendirmeleri).

Geçici olarak taşındı -> 302 Found Kaynak geçici olarak farklı bir URL’de. Tarayıcılar bunu oturum için önbelleğe alır ancak daha sonra tekrar kontrol eder. Pratikte en yaygın geçici yönlendirme.

Geçici olarak taşındı, yöntemi koru -> 307 Temporary Redirect 302 gibi, ancak HTTP yöntemini korur. Bir POST’un POST olarak kalması gereken geçici API yönlendirmeleri için kullanın.

Diğerine bak -> 303 See Other Bir POST’tan sonra istemciyi bir GET uç noktasına yönlendirmek için kullanın. Yaygın desen: POST /orders, Location: /orders/123 ile 303 döndürür, ardından istemci yeni siparişi GET’ler.

Sorun istemci tarafında mı?

Hatalı istek -> 400 Bad Request İstek sözdizimi yanlış. Geçersiz JSON, eksik Content-Type, kodu çözülemeyen gövde. İstemcinin yeniden denemeden önce isteği düzeltmesi gerekir.

Kimlik doğrulanmamış -> 401 Unauthorized Kimlik bilgisi sağlanmamış veya kimlik bilgilerinin süresi dolmuş/geçersiz. İstemci kimlik doğrulamalı (giriş, token yenileme) ve yeniden denemelidir.

Kimlik doğrulanmış ancak izin yok -> 403 Forbidden Sunucu istemcinin kim olduğunu biliyor ancak izni yok. Yeniden kimlik doğrulama işe yaramaz. Rolleri/izinleri kontrol edin.

Kaynak mevcut değil -> 404 Not Found URL herhangi bir kaynakla eşleşmiyor. Ayrıca, istemcinin bilmesine izin verilmeyen kaynakların varlığını gizlemek için yaygın olarak kullanılır (403 yerine).

Yanlış HTTP yöntemi -> 405 Method Not Allowed Uç nokta mevcut ancak bu yöntemi desteklemiyor. Örnek: salt okunur bir uç noktada DELETE denemesi. Geçerli yöntemleri listeleyen bir Allow başlığı ekleyin.

Geçerli durumla çakışma -> 409 Conflict İstek, kaynağın mevcut durumuyla çakışıyor. Yaygın kullanımlar: yinelenen oluşturma denemeleri, iyimser kilitleme hataları (sürüm uyuşmazlığı), durum makinesi ihlalleri (zaten yayınlanmış bir gönderiyi yayınlamaya çalışmak).

Kaynak silindi -> 410 Gone 404 gibi, ancak sunucu bu kaynağın eskiden var olduğunu ve kasıtlı olarak kaldırıldığını bilir. Arama motorları ve önbellekleme için 404’ten daha güçlü sinyal.

Doğrulama hatası -> 422 Unprocessable Entity Sözdizimi geçerli (düzgün JSON) ancak içerik yanlış. Eksik gerekli alanlar, yanlış veri türleri, aralık dışı değerler. İş mantığı doğrulama hataları için kullanın.

Çok fazla istek -> 429 Too Many Requests Hız sınırlaması. İstemciye ne zaman tekrar deneyeceğini söyleyen bir Retry-After başlığı ekleyin.

Sorun sunucu tarafında mı?

Beklenmeyen sunucu hatası -> 500 Internal Server Error Bir şey bozuldu. İşlenmeyen istisna, null pointer, yapılandırma hatası. “Bu bizim hatamız” için genel yakalama. Hatayı günlüğe kaydedin, dahili bilgileri istemciye ifşa etmeyin.

Uygulanmadı -> 501 Not Implemented Sunucu bu işlevselliği desteklemiyor. Tanımlanmış ancak henüz oluşturulmamış uç noktalar veya sunucunun tanımadığı HTTP yöntemleri için kullanın.

Üst hizmet başarısız oldu -> 502 Bad Gateway Sunucu bir proxy/ağ geçidi olarak hareket ediyor ve üst hizmetten geçersiz bir yanıt aldı. Bir arka uç çöktüğünde yük dengeleyiciler ve ters proxyler ile yaygındır.

Hizmet aşırı yüklü veya bakımda -> 503 Service Unavailable Sunucu şu anda isteği işleyemiyor. Aşırı yüklenmiş, bakımda veya başlatılıyor olabilir. Ne zaman geri döneceğini biliyorsanız bir Retry-After başlığı ekleyin.

Üst hizmet zaman aşımı -> 504 Gateway Timeout Sunucu bir proxy olarak hareket ediyor ve üst hizmet zamanında yanıt vermedi. 408’den (istemci zaman aşımı) farklıdır: 504, sunucunun kendi üst hizmetinin zaman aşımına uğradığı anlamına gelir.

Hızlı Başvuru Tablosu

Başarı (2xx)

Yönlendirme (3xx)

İstemci Hatası (4xx)

Sunucu Hatası (5xx)

Yaygın API Desenleri

REST CRUD işlemleri

Eklemeye değer başlıklar