Geçersiz API istek parametresi ne anlama gelir?

“Geçersiz API istek parametresi” hatası, gönderdiğiniz istekteki bir alanın API tarafından beklenen ad, tür, biçim, değer aralığı veya kullanım kurallarına uymadığı anlamına gelir. Genellikle istemci taraflı bir sorundur ve aynı isteği hiçbir değişiklik yapmadan tekrar göndermek çözüm sağlamaz. Hatanın kesin nedeni çoğunlukla HTTP durum kodu, hata kodu ve yanıt gövdesindeki açıklamada bulunur.

Hangi durumlarda oluşur?​

Bir API parametresi şu nedenlerle geçersiz sayılabilir:

• Zorunlu parametre hiç gönderilmemiştir.
• Parametre adı yanlış yazılmıştır. Örneğin userId yerine userid kullanılmıştır.
• Parametre türü yanlıştır. Sayı beklenen alana metin, dizi beklenen alana tek değer gönderilmiştir.
• Değer izin verilen aralığın dışındadır. Örneğin negatif sayfa numarası veya desteklenmeyen sonuç sayısı gönderilmiştir.
• Parametre değeri tanınmıyordur. Örneğin desteklenmeyen bir filtre, dil kodu veya durum değeri kullanılmıştır.
• Birlikte kullanılması yasak olan iki parametre aynı istekte yer almıştır.
• JSON gövdesi hatalı biçimlendirilmiş veya parametre yanlış bölümde gönderilmiştir.
• API dokümantasyonunda belirtilmeyen fazladan bir parametre eklenmiştir.

Bu hata çoğu REST API’de 400 Bad Request ile, bazı servislerde ise invalid_request, invalid_parameter veya INVALID_ARGUMENT gibi özel kodlarla gösterilir. Ancak aynı HTTP durum kodu farklı nedenleri de kapsayabildiği için yalnızca “400” değerine bakmak yeterli değildir.

Somut örnek​

Bir uygulamanın kullanıcı listesini almak için aşağıdaki isteği kabul ettiğini varsayalım:


API, limit parametresinde yalnızca 1 ile 100 arasındaki sayılara izin veriyorsa limit=250 kullanıldığında istek geçersiz sayılabilir. Benzer şekilde status=enabled gönderilirse, API yalnızca active ve passive değerlerini destekliyorsa yine aynı hata alınır.

POST isteğinde de benzer bir sorun görülebilir:


API, age alanını sayı olarak bekliyorsa metin gönderilmesi parametre doğrulamasını başarısız kılar.

Hatayı düzeltme adımları​

1. Yanıtın tamamını inceleyin. HTTP durum kodunun yanında message, error, details veya benzeri alanlarda hangi parametrenin sorunlu olduğunu arayın.
2. İsteği API dokümantasyonundaki örnekle karşılaştırın. Parametre adlarını, büyük-küçük harf kullanımını, sorgu dizesi ile JSON gövdesi arasındaki farkı kontrol edin.
3. Zorunlu alanların tamamını ekleyin ve desteklenmeyen alanları kaldırın. Bir parametrenin isteğe bağlı olması, gönderilen her değerin kabul edileceği anlamına gelmez.
4. Her değerin türünü doğrulayın. Sayı, metin, boolean, dizi ve nesne alanlarını API’nin beklediği biçimde gönderin. JSON kullanıyorsanız geçerli JSON ürettiğinizden emin olun.
5. Değer kısıtlamalarını kontrol edin. İzin verilen enum değerlerini, minimum-maksimum sınırlarını, tarih biçimini ve sayfalama kurallarını doğrulayın.
6. Birbiriyle çakışan parametreleri ayırarak deneyin. Hangi parametrenin hataya neden olduğunu bulmak için isteği en küçük geçerli biçime indirin.
7. Düzeltmeden sonra yeni isteği kaydedilen gerçek gönderimle karşılaştırın. Tarayıcı geliştirici araçları, HTTP istemcisi günlükleri veya sunucu logları burada işe yarar. İstek örneğini paylaşmadan önce API anahtarını, Authorization başlığını, çerezleri ve kişisel verileri maskeleyin.

Benzer hatalarla karıştırmayın​

Bu ayrım önemlidir: API anahtarının hatalı olması çoğunlukla parametre hatası değildir. Benzer şekilde sunucunun geçici olarak çalışmaması, doğru parametreleri değiştirerek çözülecek bir sorun olmayabilir.

Sık yapılan hatalar​

En yaygın hata, dokümantasyondaki parametre adını kendi uygulamasındaki alan adıyla karıştırmaktır. Örneğin uygulamada pageSize kullanılması, API’nin de bu adı kabul ettiği anlamına gelmez. Bir diğer hata, boş değerleri otomatik olarak isteğe eklemektir. filter=null veya boş bir dizi, parametre hiç gönderilmemesiyle aynı davranmayabilir.

Ayrıca URL ile gönderilen değerlerde karakter kodlaması, JSON gövdesinde veri türü ve başlıklarda Content-Type: application/json ayarı kontrol edilmelidir. Sorun yalnızca belirli bir kullanıcıda oluşuyorsa veri değerini; tüm isteklerde oluşuyorsa istek yapısını ve istemci kodunu önce inceleyin.

Sık sorulan sorular​

Geçersiz parametre hatasında isteği tekrar göndermek gerekir mi?​

Parametre düzeltilmeden tekrar göndermek genellikle aynı hatayı üretir. Önce hata yanıtındaki alanı ve API dokümantasyonundaki kuralları kontrol edin.

Parametre doğru göründüğü hâlde hata neden devam eder?​

Parametrenin doğru yerde gönderilip gönderilmediğini, veri türünü, büyük-küçük harf kullanımını, URL kodlamasını ve aynı istekteki başka parametrelerle çakışıp çakışmadığını inceleyin.