Geliştiriciler için API v2 Hata Kodları (Twitter/X): 401/403/429 Çözümleri ve Oranlar

Twitter/X API’siyle uğraşan herkesin yolu bir gün mutlaka hata kodlarıyla kesişir. 🚧 Uygulamanı kuruyorsun, endpoint çağrıları yapıyorsun, her şey güzel derken bir bakıyorsun: 401 Unauthorized, 403 Forbidden veya 429 Too Many Requests. 😱

Ben ilk defa 429 aldığımda “Acaba kodda mı hata var?” diye saatlerce loglara baktım. Oysa sorun bende değil, oran limitlerindeydi. İşte bu yazıda, geliştiricilerin en sık karşılaştığı bu üç hata kodunun ne anlama geldiğini, nasıl çözüleceğini ve oran (rate limit) yönetimini nasıl yapacağını konuşacağız.

API v2 ve Hata Kodları

Twitter’ın resmi API dökümantasyonu, HTTP standart hata kodlarını kullanıyor. Ama bazı kodlar özellikle sık karşımıza çıkıyor:

• 401 Unauthorized: Kimlik doğrulama sorunu.
• 403 Forbidden: Yetki kısıtlaması, erişim izni yok.
• 429 Too Many Requests: Oran limitini aştın.

Bu kodlar geliştiriciye “nerede yanlış yaptığını” gösteren ipuçları aslında.

401 Unauthorized: Kimlik Doğrulama Hatası

Ne Anlama Gelir?
API çağrın geçerli bir kimlik doğrulama token’ı içermiyor ya da token süresi dolmuş.

Olası Sebepler:

• Yanlış veya eksik Bearer Token
• OAuth 2.0 ayarlarının eksik yapılması
• Token’ın süresinin dolması

Twitter Developer docs bu hatanın %90 oranında “token” ile ilgili olduğunu belirtiyor.

Çözüm:

• Bearer token’ı kontrol et, doğru projeye mi bağlı?
• OAuth 2.0 flow’unu tekrar çalıştır.
• Gerekirse yeni token oluştur.

Benim deneyimim: Token’ı production yerine test projesinden almışım. 🤦 Bu yüzden API bana 401 döndürüyordu.

403 Forbidden: Erişim Yetkisi Yok

Ne Anlama Gelir?
Çağrı doğru kimlik doğrulama ile geldi ama o endpoint için iznin yok.

Olası Sebepler:

• Ücretsiz planda erişilemeyen endpoint’e çağrı yapmak
• Uygulamanın developer tier seviyesinin yetersiz olması
• Kullanıcı erişim izni olmadan işlem yapmaya çalışmak

Twitter API access tiers belgelerinde, farklı planların farklı limit ve izinlere sahip olduğu açıkça anlatılıyor.

Çözüm:

• Kullanmak istediğin endpoint’in hangi erişim seviyesinde açık olduğunu kontrol et.
• Gerekirse daha yüksek tier’e geç (örneğin “Basic” yerine “Pro”).
• Kullanıcıdan gerekli izinleri OAuth flow’unda aldığından emin ol.

Örnek: Ben tweets/search/all endpoint’ini kullanmaya çalışıyordum ama bu sadece Academic Research erişiminde açık. Tabii ki 403 aldım. 🙃

429 Too Many Requests: Oran Limitine Takıldın

Ne Anlama Gelir?
API çağrılarını çok sık yapıyorsun, Twitter seni limitliyor.

Olası Sebepler:

• Oran limitlerini aşmak
• Tekrar deneme mekanizması olmayan script
• Paralel çok fazla istek göndermek

Rate limit dökümantasyonuna göre, her endpoint’in dakikada belirli sayıda çağrı limiti var. Örneğin:

• tweets/lookup → 900 çağrı / 15 dakika
• tweets/search/recent → 450 çağrı / 15 dakika

Çözüm:

• Her API yanıtında dönen x-rate-limit-remaining ve x-rate-limit-reset header’larını kullan.
• Çağrıları sıraya koy, exponential backoff uygulayarak tekrar dene.
• Gereksiz istekleri azalt, cache kullan.

Ben ilk 429 aldığımda script’im her hatada tekrar deneme yapıyordu ve saniyeler içinde 1000 istek yollamıştım. 🤯 O gün “backoff stratejisi” öğrenmek zorunda kaldım.

Tablo: Hata Kodları ve Çözümler

Diyagram: API Hata Çözüm Akışı

[API Hatası] 
      ↓ 
[401 mi?] → Token / OAuth ayarlarını kontrol et 
      ↓ 
[403 mü?] → Endpoint iznini ve tier seviyesini kontrol et 
      ↓ 
[429 mu?] → Rate limit header’larına bak, backoff uygula 
      ↓ 
[Hata Çözüldü ✅]

Oran (Rate Limit) Yönetimi

Twitter API’sinde her çağrı sınırlıdır. Resmi rate limit rehberine göre:

• Limitler 15 dakikalık periyotlarla ölçülür.
• Kullanıcı başına veya uygulama başına limitler farklı olabilir.
• x-rate-limit-reset timestamp’i, ne zaman tekrar çağrı yapabileceğini gösterir.

Pro İpuçları:

• Log tut: Ne zaman 429 aldığını kaydet.
• Kuyruk sistemi kur: RabbitMQ veya Redis Queue gibi.
• Exponential backoff: İlk deneme 1sn, sonra 2sn, sonra 4sn…

Örnek: “Akademik Araştırma Projem”

Bir üniversite projesinde tweets/search/all endpoint’ini kullanıyorduk. Ama yanlışlıkla Basic tier üzerinden denedik. Sürekli 403 hatası alıyorduk. Sonra fark ettik ki Academic Research erişimine geçmemiz gerekiyor. Planı güncelledik, sorun çözüldü. 🎓

Kişisel Anekdot: “Gece Yarısı Panik”

Bir gece script’im sürekli hata veriyordu. Saatlerce kodu debug ettim. En sonunda fark ettim ki token süresi dolmuş. Yani 401 hatasının sebebi gayet basitmiş. O an “Hataların çoğu bizim dikkatsizliğimizden çıkıyor” dersini aldım.

Sonuç: Hatalar Öğretmenindir

Twitter/X API’sinde 401, 403 ve 429 hataları ilk başta sinir bozucu görünebilir. Ama aslında sana sistemin nasıl çalıştığını öğreten işaretlerdir.

• 401 → Kimlik doğrulama,
• 403 → Yetki ve tier,
• 429 → Oran limitleri.

Doğru yorumladığında, hem uygulaman daha stabil çalışır hem de sen daha yetkin bir geliştirici olursun. 🚀