13 — OAuth ve API Hata Kodları Sözlüğü

Kimin için: Hata ayıklama (debugging) yapan ve kullanıcılara doğru hata mesajları göstermek isteyen tüm geliştiriciler.
Ön koşul: Hızlı Başlangıç.
Tahmini süre: 10 dakika.

Ne Öğreneceksiniz

• TALOST ID tarafından döndürülen standart OAuth 2.0 ve API hata kodlarını,
• Her hatanın kök nedenlerini ve adım adım çözümünü,
• Bu sözlüğün sistemdeki teşhis aracı (src/lib/apps/oauth-errors.ts) ile tam senkronizasyonunu.

Standart OAuth 2.0 Hata Kodları

1. `invalid_request`

Başlık: Geçersiz İstek
Kök Nedenler:

• Zorunlu bir parametre eksik veya geçersiz (client_id, redirect_uri, response_type, state vb.).
• TALOST ID için zorunlu olan PKCE parametreleri (code_challenge ve code_challenge_method=S256) gönderilmedi.
• Token takasında code veya code_verifier parametresi eksik.
• İstek başlığında Content-Type: application/x-www-form-urlencoded belirtilmedi.

Çözüm Adımları:

1. Authorize URL parametrelerini kontrol edin.
2. PKCE üretim fonksiyonunuzun Base64URL çıktısını doğrulayın.
3. Token isteğindeki parametre adlarını kontrol edin.

2. `unauthorized_client`

Başlık: Yetkisiz İstemci
Kök Nedenler:

• Belirtilen client_id sistemde kayıtlı değil veya durumu PASİF.
• Geliştirici (DEVELOPMENT) veya Staging (STAGING) ortamındaki bir istemciye, o uygulamada ekip üyesi (APP_OWNER, APP_DEVELOPER) veya admin olmayan normal bir kullanıcı hesabıyla giriş yapılmaya çalışıldı.

Çözüm Adımları:

1. Geliştirici Portalından client_id değerini teyit edin.
2. İstemcinin durumunun AKTİF olduğunu doğrulayın.
3. Giriş yapan hesabı uygulamanın Ekip sekmesinden ekleyin.

3. `invalid_client`

Başlık: Geçersiz İstemci Kimlik Bilgileri
Kök Nedenler:

• İstemci gizli anahtarı (client_secret) hatalı, eski veya başka bir ortama ait.
• Confidential istemci için client_secret parametresi hiç iletilmedi.
• HTTP Basic Authorization başlığındaki Base64 kodlaması hatalı.

Çözüm Adımları:

1. Geliştirici Portalından istemciniz için yeni bir secret üretin (Rotate Secret) ve .env dosyanızı güncelleyin.
2. Public istemcilerde (SPA, Mobil) istemci ayarından confidential seçeneğinin kapalı olduğunu teyit edin.

4. `invalid_grant`

Başlık: Geçersiz Yetki Belgesi
Kök Nedenler:

• Yetkilendirme kodu (code) süresi doldu (Geçerlilik süresi: 5 dakika).
• Yetkilendirme kodu daha önce kullanıldı (Tek kullanımlık kuralı ihlali).
• PKCE code_verifier doğrulaması başarısız oldu (code_challenge ile uyuşmuyor).
• Token takasında gönderilen redirect_uri, ilk adımdakiyle birebir aynı değil.
• Refresh token süresi doldu (30 gün) veya iptal edildi.

Çözüm Adımları:

1. Giriş akışını baştan başlatarak taze bir kod üretin.
2. code_verifier'ın doğru çerezden okunduğundan ve silinmediğinden emin olun.
3. İki adımdaki redirect_uri adreslerinin (port ve slash dahil) harfi harfine aynı olduğunu teyit edin.

5. `unsupported_response_type`

Başlık: Desteklenmeyen Yanıt Türü
Kök Neden: response_type parametresi code haricinde bir değer (token, id_token vb.) olarak gönderildi.
Çözüm: TALOST ID yalnızca Authorization Code + PKCE akışını destekler. Parametreyi response_type=code olarak güncelleyin.

6. `unsupported_grant_type`

Başlık: Desteklenmeyen Yetki Türü
Kök Neden: POST /oauth/token isteğindeki grant_type geçersiz.
Çözüm: Yalnızca authorization_code ve refresh_token türleri desteklenmektedir.

7. `invalid_scope`

Başlık: Geçersiz Kapsam
Kök Neden: Talep edilen scope değerleri sistemde tanımlı değil veya istemciye atanmamış.
Çözüm: Desteklenen temel scopelar: openid, profile, email, offline_access, subscription.

8. `access_denied`

Başlık: Erişim Reddedildi
Kök Nedenler:

• Kullanıcının uygulamaya erişmek için aktif bir aboneliği veya lisansı bulunmuyor.
• Uygulama henüz kapalı betada (DRAFT/BETA) ve kullanıcı ekip üyesi değil.
• Uygulama bakım modunda.

Çözüm Adımları:

1. Kullanıcının TALOST ID panelinden ilgili uygulamaya ait aktif bir plana abone olmasını sağlayın.
2. Ücretsiz uygulamalarda kullanıcı onay ekranının tamamlandığını teyit edin.

9. `rate_limit_exceeded`

Başlık: İstek Sınırı Aşıldı (HTTP 429)
Kök Neden: Aynı IP veya API anahtarından izin verilen eşiğin üzerinde istek gönderildi (Authorize: 30/dk, Token: 60/dk, App API: 600/dk).
Çözüm: İstek döngülerini sınırlandırın, 1 dakika bekleyin.

10. `maintenance_mode`

Başlık: Bakım Modu
Kök Neden: Hedef uygulama veya TALOST ID platformu planlı bakım çalışması sebebiyle geçici olarak erişime kapalıdır.
Çözüm: Geliştirici Portalından bakım duyurusunun bitiş saatini kontrol edin veya bakımı sonlandırın.

11. `server_error` & `temporarily_unavailable`

Başlık: Sunucu Hatası / Geçici Olarak Kullanılamıyor
Kök Neden: Kimlik sağlayıcı sunucuda beklenmeyen bir istisna meydana geldi veya veritabanı bağlantısı kesildi.
Çözüm: Admin Konsolundaki /admin/saglik sayfasından sistem sağlığını kontrol edin.

İlgili Sayfalar

• 16. Test ve Teşhis Araçları
• 14. Güvenlik Kuralları

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/lib/apps/oauth-errors.ts