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 dakikatweets/search/recent→ 450 çağrı / 15 dakika
Çözüm:
- Her API yanıtında dönen
x-rate-limit-remainingvex-rate-limit-resetheader’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
| Hata Kodu | Anlamı | Çözüm ✅ |
|---|---|---|
| 401 | Kimlik doğrulama hatası | Token’ı yenile, OAuth flow’u tekrar çalıştır |
| 403 | Yetki/erişim sorunu | Endpoint için gerekli tier’e geç |
| 429 | Oran limiti aşıldı | Rate limit header’larını kullan, backoff uygula |
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-resettimestamp’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. 🚀
