Blog

REST API'leri Hangi HTTP Durum Kodlarını Kullanmalı?

Ashley Innocent

Ashley Innocent

13 March 2026

REST API'leri Hangi HTTP Durum Kodlarını Kullanmalı?

Kurumsal İçin Apidog

Şirket İçi (On-Premises) Dağıtım

SSO ve RBAC

SOC 2 Uyumlu

Apidog Enterprise'ı Keşfedin

Özetle

REST API'leri HTTP durum kodlarını doğru kullanmalıdır: Başarılı GET için 200, kaynak oluşturulan başarılı POST için 201, başarılı DELETE için 204, istemci hataları için 400, kimlik doğrulama hataları için 401, bulunamadı için 404 ve sunucu hataları için 500. Modern PetstoreAPI, tüm standart HTTP durum kodlarını uygun semantiklerle ve RFC 9457 hata yanıtlarıyla uygulamaktadır.

Giriş

API'niz her şey için 200 OK döndürüyor. Başarı mı? 200 OK. Doğrulama hatası mı? Gövdede bir hata mesajıyla 200 OK. Kaynak bulunamadı mı? {"error": "not found"} ile 200 OK. Kimlik doğrulama hatası mı? Tahmin ettiniz — 200 OK.

Bu yanlış. HTTP durum kodlarının bir nedeni var. Yanıt gövdesini ayrıştırmadan istemcilere ne olduğunu söylerler. Önbellekler, proxy'ler ve izleme araçları durum kodlarına güvenir. Hatalar için 200 döndürdüğünüzde, tüm HTTP ekosistemini bozmuş olursunuz.

Eski Swagger Petstore, durum kodu hataları yaptı: 201 döndürmesi gereken POST istekleri için 200 döndürme, 204 döndürmesi gereken DELETE işlemleri için 200 kullanma ve önemli hata kodlarını eksik bırakma. Modern PetstoreAPI, tüm uç noktalarda uygun HTTP semantiğini uygulayarak bunu düzeltir.

💡
REST API'leri oluşturuyor veya test ediyorsanız, Apidog durum kodu kullanımını doğrulamanıza, hata senaryolarını test etmenize ve API'nizin HTTP standartlarına uymasını sağlamanıza yardımcı olur. Beklenen durum kodlarını tanımlayabilir, otomatik testler çalıştırabilir ve dağıtımdan önce yanlış yanıtları yakalayabilirsiniz.
button

Bu kılavuzda, REST API'leri için hangi HTTP durum kodlarının önemli olduğunu, her birini ne zaman kullanacağınızı ve Modern PetstoreAPI'nin bunları nasıl doğru bir şekilde uyguladığını öğreneceksiniz.

Durum Kodu Sorunu

Birçok API, durum kodlarını sonradan akla gelen bir şey olarak görür. Sonuç: bozuk HTTP semantiği ve kafası karışık istemciler.

"Her Şey İçin 200 OK" Anti-Paterni

// Başarılı
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Hata (ama hala 200!)
GET /users/999
200 OK
{"error": "Kullanıcı bulunamadı"}

// Doğrulama hatası (hala 200!)
POST /users
200 OK
{"error": "E-posta gerekli"}

Sorunlar:

Neden Böyle Oluyor?

Geliştiriciler 200 döndürür çünkü:

  1. Diğer durum kodlarını bilmiyorlar
  2. Durum kodlarının isteğe bağlı olduğunu düşünüyorlar
  3. İstemcileri "bozmaktan" kaçınmak istiyorlar
  4. Kötü örnekleri kopyalıyorlar (eski Swagger Petstore gibi)

REST API'leri İçin Temel HTTP Durum Kodları

Tüm 60'tan fazla HTTP durum koduna ihtiyacınız yok. Bu temel olanlara odaklanın.

Hızlı Başvuru

Başarılı (2xx):

İstemci Hataları (4xx):

Sunucu Hataları (5xx):

Başarı Kodları (2xx)

Başarı kodları, isteğin başarılı olduğunu gösterir. Farklı kodlar farklı anlamlar taşır.

200 OK

Kullanım alanı: Veri döndüren başarılı GET, PUT, PATCH istekleri.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Kullanmayın: Kaynak oluşturan POST istekleri için (201 kullanın), DELETE istekleri için (204 kullanın).

201 Oluşturuldu

Kullanım alanı: Yeni bir kaynak oluşturan başarılı POST istekleri.

POST /pets
201 Oluşturuldu
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Ana noktalar:

Modern PetstoreAPI, kaynak oluşturan tüm POST işlemleri için 201 döndürür.

204 İçerik Yok

Kullanım alanı: Yanıt gövdesi olmayan başarılı DELETE, PUT veya PATCH istekleri.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 İçerik Yok

Ana noktalar:

İstemci Hata Kodları (4xx)

İstemci hata kodları, istemcinin bir hata yaptığını gösterir. İstek, değişiklik yapılmadan tekrar denenmemelidir.

400 Hatalı İstek

Kullanım alanı: Hatalı biçimlendirilmiş istekler, geçersiz JSON, eksik zorunlu alanlar.

POST /pets
400 Hatalı İstek
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Doğrulama Hatası",
  "status": 400,
  "detail": "İstek doğrulaması başarısız oldu",
  "invalid-params": [
    {
      "name": "name",
      "reason": "İsim gerekli"
    }
  ]
}

Modern PetstoreAPI, tüm hata yanıtları için RFC 9457 formatını kullanır.

401 Yetkilendirilmemiş

Kullanım alanı: Eksik veya geçersiz kimlik doğrulama kimlik bilgileri.

GET /pets
401 Yetkilendirilmemiş
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Kimlik Doğrulama Gerekli",
  "status": 401,
  "detail": "Geçerli kimlik doğrulama bilgileri gerekli"
}

Ana noktalar:

403 Yasak

Kullanım alanı: Kimliği doğrulanmış kullanıcının izni yok.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Yasak

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Yetersiz İzinler",
  "status": 403,
  "detail": "Bu evcil hayvanı silme izniniz yok"
}

401'den Farkı:

404 Bulunamadı

Kullanım alanı: Kaynak mevcut değil.

GET /pets/nonexistent-id
404 Bulunamadı

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Bulunamadı",
  "status": 404,
  "detail": "Evcil hayvan bulunamadı"
}

Kullanmayın: Yetkilendirme hataları için (403 kullanın), doğrulama hataları için (400 kullanın).

409 Çakışma

Kullanım alanı: Yinelenenler veya sürüm uyuşmazlıkları gibi kaynak çakışmaları.

POST /pets
409 Çakışma

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Yinelenen Kaynak",
  "status": 409,
  "detail": "Bu mikroçip ID'sine sahip bir evcil hayvan zaten mevcut"
}

422 İşlenemeyen Varlık

Kullanım alanı: Geçerli istek formatı ama semantik hatalar.

POST /pets
422 İşlenemeyen Varlık

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "İş Kuralı İhlali",
  "status": 422,
  "detail": "Her hane başına 5'ten fazla evcil hayvan sahiplenilemez"
}

400'den Farkı:

429 Çok Fazla İstek

Kullanım alanı: İstek limiti aşıldı.

GET /pets
429 Çok Fazla İstek
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "İstek Limiti Aşıldı",
  "status": 429,
  "detail": "Saatte 100 istek limiti aşıldı"
}

Modern PetstoreAPI IETF hız limiti başlıklarını kullanır.

Sunucu Hata Kodları (5xx)

Sunucu hata kodları, sunucunun başarısız olduğunu gösterir. İstemciler bu istekleri yeniden deneyebilir.

500 Dahili Sunucu Hatası

Kullanım alanı: Beklenmedik sunucu hataları.

GET /pets
500 Dahili Sunucu Hatası

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Dahili Sunucu Hatası",
  "status": 500,
  "detail": "Beklenmedik bir hata oluştu"
}

Ekleme: Üretimde yığın izleri, dahili ayrıntılar, veritabanı hataları.

503 Hizmet Kullanılamıyor

Kullanım alanı: Geçici kullanılamama (bakım, aşırı yük).

GET /pets
503 Hizmet Kullanılamıyor
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Hizmet Kullanılamıyor",
  "status": 503,
  "detail": "Hizmet bakım nedeniyle geçici olarak kullanılamıyor"
}

İstemcilere ne zaman yeniden deneyeceklerini bildirmek için Retry-After başlığını ekleyin.

Modern PetstoreAPI Durum Kodlarını Nasıl Kullanır?

Modern PetstoreAPI, tüm uç noktalarda uygun HTTP semantiğini uygular.

Örnek: Evcil Hayvan Yönetimi

// Evcil hayvanları listele
GET /pets
200 OK

// Evcil hayvan oluştur
POST /pets
201 Oluşturuldu
Location: https://petstoreapi.com/pets/{id}

// Evcil hayvan al
GET /pets/{id}
200 OK (bulundu) veya 404 Bulunamadı

// Evcil hayvan güncelle
PUT /pets/{id}
200 OK (gövde ile) veya 204 İçerik Yok

// Evcil hayvan sil
DELETE /pets/{id}
204 İçerik Yok (başarılı) veya 404 Bulunamadı

Hata Yanıtları

Tüm hatalar RFC 9457 formatını kullanır:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Doğrulama Hatası",
  "status": 400,
  "detail": "İstek doğrulaması başarısız oldu",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Ad 1 ile 100 karakter arasında olmalıdır"
    }
  ]
}

Tam örnekler için Modern PetstoreAPI hata işleme dokümantasyonuna bakın.

Apidog ile Durum Kodlarını Test Etme

Apidog, tüm senaryolarda durum kodu davranışını test etmenize yardımcı olur.

Beklenen Durum Kodlarını Tanımla

paths:
  /pets:
    post:
      responses:
        '201':
          description: Evcil hayvan oluşturuldu
        '400':
          description: Doğrulama hatası
        '401':
          description: Kimlik doğrulama gerekli
        '429':
          description: İstek limiti aşıldı

Tüm Senaryoları Test Et

Aşağıdakiler için test senaryoları oluşturun:

Otomatik Test

// Apidog test betiği
pm.test("Başarılı oluşturma için 201 döndürür", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Eksik zorunlu alanlar için 400 döndürür", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

Kaçınılması Gereken Yaygın Hatalar

Hata 1: POST İçin 200 Kullanmak

// Yanlış
POST /pets
200 OK

// Doğru
POST /pets
201 Oluşturuldu
Location: https://petstoreapi.com/pets/{id}

Hata 2: DELETE İçin 200 Kullanmak

// Yanlış
DELETE /pets/{id}
200 OK
{"message": "Başarıyla silindi"}

// Doğru
DELETE /pets/{id}
204 İçerik Yok

Hata 3: 401 ve 403'ü Karıştırmak

// Yanlış: Kullanıcı kimliği doğrulanmış ama izni yok
401 Yetkilendirilmemiş

// Doğru
403 Yasak

Hata 4: İstemci Hataları İçin 500 Kullanmak

// Yanlış: Doğrulama hatası 500 döndürüyor
POST /pets
500 Dahili Sunucu Hatası

// Doğru
POST /pets
400 Hatalı İstek

Sonuç

HTTP durum kodları isteğe bağlı değildir. HTTP spesifikasyonunun bir parçasıdır ve uygun REST API'leri oluşturmak için vazgeçilmezdir.

Doğru durum kodlarını kullanın:

Modern PetstoreAPI, tüm uç noktalarda doğru durum kodu kullanımını göstermektedir. Doğru uygulamayı görmek için REST API dokümantasyonunu inceleyin.

API'nizin HTTP standartlarına uygun olduğundan emin olmak için durum kodlarınızı Apidog ile test edin.

Sıkça Sorulan Sorular

Başarılı DELETE için 200 mü yoksa 204 mü kullanmalıyım?

204 İçerik Yok kullanın. Yanıt gövdesi olmadan başarıyı gösterir ve bant genişliğinden tasarruf sağlar. Yalnızca silinen kaynak hakkında bilgi döndürmeniz gerekiyorsa 200 kullanın.

400 ve 422 arasındaki fark nedir?

400, isteğin hatalı biçimlendirildiği anlamına gelir (geçersiz JSON, yanlış tipler). 422 ise isteğin iyi biçimlendirilmiş ancak iş kurallarını ihlal ettiği anlamına gelir.

401'i ne zaman, 403'ü ne zaman kullanmalıyım?

401 "kendinizi doğrulayın" anlamına gelir (eksik veya geçersiz kimlik bilgileri). 403 ise "kimliğiniz doğrulandı ama yetkiniz yok" anlamına gelir (yetersiz izinler).

Kullanıcıların erişemediği kaynaklar için 404 mü yoksa 403 mü döndürmeliyim?

Kaynak mevcutsa ancak kullanıcının izni yoksa 403 döndürün. Kaynağın varlığını yetkisiz kullanıcılardan gizlemek istiyorsanız 404 döndürün.

Tüm durum kodu senaryolarını nasıl test ederim?

Başarı, doğrulama hataları, kimlik doğrulama hataları, bulunamadı ve sunucu hataları için test senaryoları oluşturmak üzere Apidog kullanın. CI/CD'de otomatik testler çalıştırın.

Hız sınırlaması için hangi durum kodu?

RateLimit-* başlıklarıyla birlikte 429 Çok Fazla İstek kullanın. İstemcilere ne zaman yeniden deneyebileceklerini bildirmek için Retry-After ekleyin.

Tüm sunucu hataları için 500 kullanmalı mıyım?

Beklenmedik hatalar için 500 kullanın. Üst akış hizmeti hataları için 502, geçici kullanılamama için 503 ve zaman aşımları için 504 kullanın.

Modern PetstoreAPI hataları nasıl işler?

Tüm hatalar, uygun durum kodlarıyla RFC 9457 formatını kullanır. Örnekler için hata işleme dokümantasyonuna bakın.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir