Bir API entegrasyonu çalışmadığında yalnızca “API cevap vermiyor” demek teşhis için yeterli değildir. HTTP durum kodu, endpoint, istek yöntemi, authentication header, payload ve rate limit bilgileri problemin hangi tarafta olduğunu anlamak için birlikte değerlendirilmelidir.
Bu rehberde API bağlantılarında sık karşılaşılan 401, 403, 429 ve 500 hatalarının ne anlama geldiğini ve problemi hangi sırayla kontrol etmeniz gerektiğini adım adım inceleyeceğiz.
Önce gerçek API cevabını kaydedin
Şunları birlikte not alın:
- İstek URL’si
- HTTP yöntemi
- Durum kodu
- Response body
- Response header’ları
- İstek zamanı
- Varsa request ID
Örneğin yalnız:
API çalışmadı
yerine:
POST /v1/orders
HTTP 401
Response: invalid_token
bilgisi çok daha faydalıdır.
Bir SaaS ürünü henüz satın alma aşamasındaysa API’nin yalnız mevcut olup olmadığını değil, dokümantasyonunu, rate limitlerini ve gerekli işlemleri destekleyip desteklemediğini de değerlendirin. Bunun için SaaS Seçerken Nelere Dikkat Edilmeli? kontrol listesini kullanabilirsiniz.
1. Endpoint doğru mu?
API dokümantasyonundaki base URL’yi kontrol edin.
Örneğin:
https://api.example.com/v1/
yerine yanlışlıkla:
https://example.com/v1/
kullanılıyor olabilir.
Ayrıca test ve production ortamlarını karıştırmayın.
Örneğin:
Sandbox token + Production endpoint
kombinasyonu çalışmayabilir.
2. HTTP yöntemini kontrol edin
Endpoint:
POST /orders
beklerken:
GET /orders
gönderiyorsanız hata alabilirsiniz.
API dokümantasyonundan:
- GET
- POST
- PUT
- PATCH
- DELETE
yöntemini doğrulayın.
3. 401 Unauthorized ne anlama gelir?
401 hatası çoğunlukla API’nin geçerli kimlik doğrulama bilgisi alamadığını gösterir.
Kontrol edin:
- API token doğru mu?
- Token süresi doldu mu?
- Authorization header doğru mu?
- Yanlış ortama ait anahtar mı kullanılıyor?
- Anahtar iptal edilmiş olabilir mi?
Örneğin API şu formatı istiyor olabilir:
Authorization: Bearer TOKEN
Ancak siz:
Authorization: TOKEN
gönderiyorsanız authentication başarısız olabilir.
4. Token başında veya sonunda boşluk var mı?
Environment variable’dan okunan değerlerde istemeden boşluk veya satır sonu bulunabilir.
Örneğin:
"abc123 "
ile:
"abc123"
aynı değildir.
Token’ı log’a açık şekilde yazmadan uzunluğunu veya hash benzeri güvenli kontrol bilgisini doğrulayabilirsiniz.
5. 403 Forbidden ne anlama gelir?
403 durumunda kimlik doğrulama başarılı olabilir ancak hesabın ilgili işleme yetkisi bulunmayabilir.
Örneğin token:
read:orders
yetkisine sahipken siz:
POST /orders
çağrısı yapıyor olabilirsiniz.
Kontrol edin:
- API scope
- Kullanıcı rolü
- Uygulama yetkisi
- IP allowlist
- Hesap kısıtlaması
6. IP allowlist kullanılıyor mu?
Bazı API servisleri yalnız önceden tanımlanmış IP adreslerinden gelen isteklere izin verir.
Sunucunuzun dış IP adresi değiştiyse API 403 döndürebilir.
Özellikle:
- Hosting taşıması
- Proxy değişikliği
- Yeni sunucu
sonrasında bu kontrol önemlidir.
7. 401 ile 403 arasındaki fark nedir?
Basitleştirilmiş olarak:
401 → Kim olduğun doğrulanamadı
403 → Kim olduğun biliniyor ancak bu işleme izin yok
şeklinde düşünülebilir.
Ancak bazı API sağlayıcıları güvenlik nedeniyle farklı durum kodları kullanabilir.
Her zaman sağlayıcının dokümantasyonunu kontrol edin.
8. 429 Too Many Requests ne anlama gelir?
429, belirli zaman aralığında izin verilenden fazla API isteği gönderildiğini gösterir.
Örneğin:
Limit: 100 istek / dakika
Gerçek trafik: 350 istek / dakika
ise rate limit aşılabilir.
9. Rate limit header’larını kontrol edin
API sağlayıcısına göre cevapta şu tür header’lar bulunabilir:
Retry-After
X-RateLimit-Limit
X-RateLimit-Remaining
İsimler sağlayıcıya göre değişebilir.
Dokümantasyonda limitlerin nasıl bildirildiğini kontrol edin.
10. 429 aldığınızda sürekli yeniden istek göndermeyin
Şu yapı problemi büyütebilir:
429 geldi
↓
Hemen tekrar dene
↓
429
↓
Hemen tekrar dene
Bunun yerine sağlayıcının önerdiği bekleme süresini kullanın.
Uygun entegrasyonlarda exponential backoff benzeri kontrollü retry yöntemi uygulanabilir.
11. Cache kullanarak gereksiz API çağrılarını azaltın
Her sayfa görüntülemesinde değişmeyen veriyi tekrar tekrar API’den istemek rate limit tüketebilir.
Örneğin:
Şehir listesi
Ürün kategorileri
Sabit ayarlar
uygun süreyle cache edilebilir.
12. 500 Internal Server Error ne anlama gelir?
API sağlayıcısı 500 döndürüyorsa sunucu tarafında beklenmeyen bir hata oluşmuş olabilir.
Ancak isteğiniz belirli bir edge case’i tetikliyor da olabilir.
Kontrol edin:
- Response body
- Request ID
- Gönderilen payload
- Sağlayıcının status sayfası
- Aynı endpoint’in başka istekte çalışıp çalışmadığı
13. 500 hatasında aynı işlemi körlemesine tekrar etmeyin
Özellikle şu işlemlerde dikkatli olun:
- Ödeme oluşturma
- Sipariş oluşturma
- Para transferi
- E-posta gönderimi
İstek sunucuda başarılı olmuş ancak cevap sırasında 500 oluşmuş olabilir.
Körlemesine tekrar göndermek mükerrer işlem oluşturabilir.
Uygun API’lerde idempotency key kullanılabilir.
14. Content-Type doğru mu?
API JSON bekliyorsa:
Content-Type: application/json
gerekebilir.
Form data gönderiyorsanız farklı content type kullanılabilir.
Dokümantasyondaki formatı takip edin.
15. JSON geçerli mi?
Örneğin:
{
"name": "Kadir",
"email": "test@example.com"
}
geçerli olabilir.
Ancak eksik virgül veya bozuk karakter nedeniyle API body’yi okuyamayabilir.
Payload’ı sunucudan çıktığı gerçek haliyle kontrol edin.
16. Zorunlu parametre eksik olabilir
API dokümantasyonunda:
customer_id
amount
currency
zorunlu olabilir.
Sadece HTTP koduna bakmayın.
Response body çoğu zaman hangi alanın eksik olduğunu belirtir.
17. Tarih ve saat formatını kontrol edin
API:
2026-09-12T14:30:00Z
beklerken farklı bir tarih biçimi gönderiyor olabilirsiniz.
Saat dilimi ve UTC farkları da entegrasyon problemleri oluşturabilir.
18. İstek sunucudan gerçekten çıkıyor mu?
Uygulama kodunuz API’ye ulaşmadan hata veriyor olabilir.
Kontrol edin:
- DNS çözülüyor mu?
- TLS bağlantısı kuruluyor mu?
- Firewall çıkışı engelliyor mu?
- Timeout oluşuyor mu?
19. cURL ile minimum istek oluşturun
Uygulama kodundan bağımsız bir test yapmak teşhisi kolaylaştırabilir.
Örneğin genel mantık:
curl -X GET
-H "Authorization: Bearer TOKEN"
https://api.example.com/v1/account
Gerçek token’ı forumda veya herkese açık loglarda paylaşmayın.
20. Timeout süresini kontrol edin
API normalde:
3 saniye
içinde cevap verirken bazı işlemler:
20 saniye
sürebilir.
Client timeout:
5 saniye
ise istek API tarafında işlenmeye devam ederken uygulamanız bağlantıyı kapatabilir.
API hata kodu hızlı teşhis
401 → Authentication / token
403 → Permission / scope / IP
429 → Rate limit
500 → API sunucu hatası veya işlenemeyen edge case
Hızlı kontrol sırası
- Endpoint doğru mu?
- HTTP method doğru mu?
- Test ve production karıştı mı?
- Token geçerli mi?
- Authorization header doğru mu?
- Scope yeterli mi?
- IP allowlist var mı?
- Rate limit aşıldı mı?
- Content-Type doğru mu?
- Payload geçerli mi?
- Timeout yeterli mi?
- Request ID kaydedildi mi?
Güvenlik notu
Forumda veya destek talebinde:
- API key
- Access token
- Client secret
- Authorization header
- Müşteri kişisel verisi
paylaşmayın.
Log gönderecekseniz bu bilgileri maskeleyin.
API isteği doğrudan sizin sisteminizden çıkmıyor, bir SaaS sağlayıcısının olay gerçekleştiğinde sisteminize bildirim göndermesi bekleniyorsa problem API çağrısından çok webhook tarafında olabilir. Bu durumda Webhook Çalışmıyor: Olaylar Neden Ulaşmıyor ve Nasıl Test Edilir? rehberine geçin.
Sonuç
API bağlantısı çalışmadığında doğru teşhis:
Endpoint → method → authentication → permission → rate limit → payload → sunucu cevabı
sırasıyla yapılmalıdır.
401, 403, 429 ve 500 aynı problemi ifade etmez.
HTTP kodunu response body ve loglarla birlikte değerlendirdiğinizde sorunun kendi uygulamanızda mı, hesabın yetkilerinde mi yoksa API sağlayıcısında mı olduğunu çok daha hızlı belirleyebilirsiniz.