Hata Bildirmeden Önce

Bir şey çalışmıyorsa, sorunun sizden mi yoksa bizden mi kaynaklandığını anlamanın en hızlı yolu aynı isteği farklı bir araçtan çalıştırmaktır.

"API bozuk" raporlarının yaklaşık 10'da 9'u yanlış yapılandırılmış bir temel URL, eski bir API anahtarı, hatalı bir model adı veya üç SDK sürümü öncesine ait bir öğreticiden kopyalanmış hatalı istek gövdesi olduğu ortaya çıkar.

Hızlı Kendi Kendine Test

Bu curl komutunu bir terminale kopyalayın. YOUR_KEY yerine Dashboard'dan aldığınız API anahtarınızı yazıp çalıştırın. Normal bir yanıt alıyorsanız API anahtarınız, ağınız ve arka ucumuz sorunsuz demektir — sorun varsa istemci kodunuzda veya ortamınızdadır.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Adım Adım Kontrol Listesi

API anahtarınız geçerli mi?

Dashboard → API Keys'i açın ve anahtarın kodunuzun kullandığıyla eşleştiğini doğrulayın. Yaygın bir tuzak, kopyala-yapıştır sırasında "sk-air-" önekinden önce boşluk kalmasıdır.

Belirti: 401 Unauthorized.

Temel URL doğru mu?

Temel URL https://api.airforce/v1 olmalıdır — http değil, /v1 soneki zorunludur. OpenAI'nin v1 yolundan önce yazılmış öğreticiler zaman zaman bunu atlar.

Belirti: 404 Not Found veya curl takılı kalıyor.

Model adı doğru yazılmış mı?

Model ID'leri büyük/küçük harfe duyarlıdır. Tam ID'yi doğrulamak için Models sayfasını ziyaret edin ya da GET /v1/models çağrısı yapın. Yazım hatası olan veya kullanımdan kaldırılmış bir model, "çalışıyor ama yanlış" yerine temiz bir hata döndürür.

Belirti: 400 unknown_model veya 404 model_not_found.

İstek gövdesi doğru biçimlendirilmiş mi?

Sohbet tamamlamaları messages dizisi kullanır. Görseller prompt + n kullanır. Sesli TTS input + voice kullanır. /v1/images/generations endpoint'ine sohbet biçimli bir gövde göndermek 400 döndürür — belgeler arasında kod parçacığı kopyalarken bunu kaçırmak kolaydır.

Belirti: 400 ile yanıt gövdesinde sorunlu alan belirtilir.

Hız sınırına veya kota üst sınırına ulaştınız mı?

429 = bu dakika çok fazla istek. 402 = planınız veya bakiyeniz tükendi. Her ikisi de Dashboard'da görünür. Ücretsiz katman isteklerinin ücretli plan isteklerinden ayrı sınırları vardır; bu nedenle ücretli bir model iyi yanıt verirken ücretsiz biri hız sınırına takılabilir.

Belirti: 429 Too Many Requests veya 402 Payment Required.

Model şu an gerçekten çalışıyor mu?

Models sayfasını kontrol edin — sağlayıcı kesintileri "degraded" veya "major outage" olarak görünür. Bir model çökmüşken diğerleri çalışıyorsa bu istemci hatası değil, bizim yönlendirme ile atladığımız sağlayıcı taraflı bir sorundur.

Belirti: belirli bir model 5xx döndürürken diğerleri çalışıyor.

HTTP Durum Kodları Ne Anlama Gelir

Her hata yanıtı standart bir HTTP durum kodu taşır. Her birinin ne anlama geldiğini bilmek bir destek talebinin önüne geçer.

Gerçekten Bir Hata Olduğunda

Yukarıdaki curl kendi kendine testi çalışıyor ama kodunuzdan gelen tamamen aynı istek çalışmıyorsa sorun istemcinizdedir (veya kullandığı kütüphanededir). Kendi kendine test 5xx ile başarısız oluyorsa ya da isteğinize uymayan bir mesajla 4xx dönüyorsa, bunu bildirmeye değer.

Etkili Bildirim Nasıl Yapılır

Dashboard'dan bir destek talebi açın veya Discord'da #support kanalında paylaşın. Şunları ekleyin:

• Tam HTTP durum kodu ve yanıt gövdesi (varsa cf-ray yanıt başlığı da).
• UTC cinsinden yaklaşık zaman damgası.
• Model adı ve çağırdığınız endpoint.
• Sorunu yeniden üreten minimal bir cURL (gerçek API anahtarınızı maskeleyin!).
• Yukarıdaki kendi kendine testin aynı anahtarla sizin için çalışıp çalışmadığı.

Discord'da #support kanalında sor