Bir API tüm yanıtları 200 OK dönüp hata bilgisini yalnızca JSON içindeki success alanına yazıyorsa, istemci başarısızlığı anlamak için her yanıtı özel olarak incelemek zorunda kalır. HTTP durum kodları bunun için ortak bir dil sunar. Yine de kod seçimi tek başına yeterli değildir: anlaşılır, kararlı ve hassas bilgi sızdırmayan bir hata gövdesi de gerekir.

Başarılı yanıtların farkı

200 OK, isteğin başarıyla işlendiği birçok okuma veya güncelleme işlemi için uygundur. Yeni bir kaynak oluşturduğunuzda 201 Created kullanabilir ve kaynak adresini Location başlığında gösterebilirsiniz. Yanıt gövdesi gerekmeyen başarılı bir silme veya güncelleme için 204 No Content tercih edilebilir; bu kodla yanıt gövdesi gönderilmemelidir.

Bir işlemi kuyruğa alıp henüz tamamlamadıysanız 202 Accepted daha açıklayıcı olabilir. Örneğin rapor oluşturma isteği alındığında kullanıcıya bir işlem kimliği ve durumu takip edebileceği adres verin. 202, işin kesinlikle başarılı olacağını garanti etmez.

İstemcinin düzeltebileceği hatalar

400 Bad Request, isteğin sunucunun işleyemeyeceği biçimde olması gibi genel istemci hatalarında kullanılır. JSON biçimi bozuksa anlamlı bir örnektir. Bazı API'ler biçimi doğru ancak alan doğrulaması başarısız olan isteklerde 422 Unprocessable Content kullanır. İkisinden hangisini seçerseniz seçin kuralları tutarlı belgeleyin.

401 Unauthorized, istek için geçerli kimlik doğrulama bilgisi bulunmadığında kullanılır. 403 Forbidden ise sunucunun isteği anladığı fakat izin vermediği durumlara işaret eder. Yetkisi olmayan birine kaynağın varlığını göstermemek isteyen uygulamalar, güvenlik politikasına göre 404 döndürebilir. Önemli olan istemcinin yetki modelini doğru anlaması ve sunucunun nesne düzeyindeki denetimi gerçekten yapmasıdır.

Bulunamayan kaynak için 404 Not Found, mevcut durumla çakışan bir işlem için 409 Conflict uygun olabilir. Örneğin aynı benzersiz sipariş numarasıyla yeni bir kayıt oluşturma girişimini 409 ile açıklayabilirsiniz. Çok fazla istek için 429 Too Many Requests ve destekleniyorsa Retry-After başlığı istemciye bekleme konusunda yardımcı olur.

Hata gövdesini nasıl hazırlamalı?

JSON
{
  "code": "validation_failed",
  "message": "Gönderilen bilgileri kontrol edin.",
  "errors": {
    "quantity": ["Adet en az 1 olmalıdır."]
  },
  "request_id": "req_01example"
}

code alanını istemcilerin güvenle kullanabileceği kısa bir makine kodu olarak düşünün. message insan tarafından okunabilir, errors ise alan bazlı açıklamalar içerebilir. İstek kimliği, kullanıcının destek talebini sunucu kayıtlarıyla eşleştirmeye yarar. Bu değer rastgele üretilmeli; kullanıcı e-postası veya sipariş bilgisi içermemelidir.

500 dönerken neyi göstermemeli?

500 Internal Server Error, beklenmedik bir sunucu sorununu belirtir. SQL sorgusunu, dosya yolunu, hata yığınını veya gizli anahtarı yanıt olarak göstermeyin. Ayrıntıyı erişimi kısıtlı sunucu günlüğüne yazıp istemciye genel bir açıklama ve istek kimliği döndürün. Bir bağımlılık geçici olarak kullanılamıyorsa, duruma göre 503 Service Unavailable ve Retry-After değerlendirilebilir.

İstemcinin bütün 4xx hataları tekrar denemesini veya bütün 5xx hatalarını sonsuza kadar tekrarlamasını önleyin. Doğrulama hatası kullanıcı verisi düzelmeden genellikle iyileşmez; geçici sunucu hataları ise sınırlı ve güvenli bir retry politikası gerektirir. Özellikle sipariş oluşturan isteklerde tekrarın çift kayıt üretmeyeceğinden emin olun.

Başlangıç için ekibinizin kullanacağı kodları küçük bir tabloda tanımlayın ve örnek yanıtlarla test edin. MDN durum kodları başvurusu, her kodun HTTP anlamını kontrol etmek için iyi bir başvuru kaynağıdır.