Konu Görünümü

***Kadir***

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:

Kod:
API çalışmadı

yerine:

Kod:
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:

Kod:
https://api.example.com/v1/

yerine yanlışlıkla:

Kod:
https://example.com/v1/

kullanılıyor olabilir.

Ayrıca test ve production ortamlarını karıştırmayın.

Örneğin:

Kod:
Sandbox token + Production endpoint

kombinasyonu çalışmayabilir.

2. HTTP yöntemini kontrol edin

Endpoint:

Kod:
POST /orders

beklerken:

Kod:
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:

Kod:
Authorization: Bearer TOKEN

Ancak siz:

Kod:
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:

Kod:
"abc123 "

ile:

Kod:
"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:

Kod:
read:orders

yetkisine sahipken siz:

Kod:
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:

Kod:
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:

Kod:
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:

Kod:
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:

Kod:
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:

Kod:
Ş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:

Kod:
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:

Kod:
{
  "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:

Kod:
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:

Kod:
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:

Kod:
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:

Kod:
3 saniye

içinde cevap verirken bazı işlemler:

Kod:
20 saniye

sürebilir.

Client timeout:

Kod:
5 saniye

ise istek API tarafında işlenmeye devam ederken uygulamanız bağlantıyı kapatabilir.

API hata kodu hızlı teşhis

Kod:
→ Authentication / token
→ Permission / scope / IP
→ Rate limit
→ 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.