Temel kılavuzlar
API hatalarını yönetme
Hata kodlarını okuyun, yalnızca yararlı olduğunda yeniden deneyin ve Request ID'yi saklayın
Hataları HTTP durum kodlarına ve code değerine göre yönetin. message alanı insanlar için yazılmıştır ve önceden haber verilmeksizin değişebilir.
Chat Completions ve Responses, OpenAI tarzı bir error nesnesi kullanır. Anthropic Messages ve Gemini kendi hata formatlarını korurlar, bu nedenle her TokenLab API'si için tek bir ayrıştırıcı (parser) kullanmayın.
{
"error": {
"message": "İnsan tarafından okunabilir açıklama",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}TokenLab tarafından oluşturulan OpenAI uyumlu hatalarda yalnızca message ve type her zaman mevcuttur. Diğer alanlar ilgili olduklarında görünürler.
Durum kodları
| Durum | Anlamı | Tipik eylem |
|---|---|---|
400 | Bir alan, model ID veya girdi geçersiz | İsteği düzeltin; değiştirmeden tekrar etmeyin |
401 | API anahtarı eksik, geçersiz, süresi dolmuş veya iptal edilmiş | Anahtarı değiştirin |
402 | Bakiye veya API anahtarı limiti çok düşük | Bakiye yükleyin, limiti artırın veya isteği azaltın |
403 | Bu anahtar kaynağı veya modeli kullanamaz | Anahtarın izinlerini veya modeli değiştirin |
404 | Kaynak mevcut değil veya artık erişilebilir değil | ID'yi ve onu oluşturan API anahtarını kontrol edin |
413 | İstek veya yüklenen dosya çok büyük | Girdiyi belgelenen model veya endpoint limitine göre azaltın |
429 | İstek limitine ulaşıldı | Retry-After süresini bekleyin |
500–504 | Servis kullanılamıyor veya ağ hatası | Yalnızca retryable: true olduğunda yeniden deneyin; retry_after değerine ve deneme sınırına uyun |
Yaygın hata kodları
| Kod | Anlamı | Ne değiştirilmeli |
|---|---|---|
invalid_api_key | API anahtarı eksik, geçersiz, etkin değil veya iptal edilmiş | Authorization başlığını ve anahtar değerini kontrol edin |
expired_api_key | API anahtarının süresi doldu | Aktif bir anahtar oluşturun veya seçin |
insufficient_balance | Hesap bakiyesi isteği karşılayamıyor | Bakiye ekleyin, isteği azaltın veya daha düşük fiyatlı bir model seçin |
quota_exceeded | API anahtarı kendi limitine ulaştı | Anahtarın limitini artırın veya yetkili başka bir anahtar kullanın |
model_not_allowed | Anahtar istenen modeli kullanamaz | Anahtarın model listesini güncelleyin veya izin verilen bir model seçin |
model_not_found | Model ID bilinmiyor veya mevcut değil | /v1/models kısmını okuyun ve güncel bir model ID kullanın |
context_length_exceeded | Girdi, modelin kabul ettiğinden daha uzun | Geçmişi kaldırın veya daha büyük bir bağlam penceresine sahip bir model seçin |
rate_limit_exceeded | Mevcut pencerede çok fazla istek gönderildi | Retry-After süresini bekleyin |
payload_too_large | İstek gövdesi veya dosya endpoint limitini aşıyor | Girdiyi azaltın veya sıkıştırın |
all_channels_failed | Seçilen model bu isteği karşılayamıyor | Yalnızca retryable: true olduğunda yeniden deneyin; retry_after değerine ve deneme sınırına uyun |
timeout_error | İstek zamanında tamamlanmadı | Yalnızca işlem tekrarlanması güvenli olduğunda yeniden deneyin |
503 all_channels_failed veya 503 delivery_tier_unavailable her zaman geçici kesinti anlamına gelmez. Seçilen Delivery katmanında istenen işlemi sağlayan bir kaynak yoksa retryable değeri false olur ve retry_after döndürülmez. Aynı isteği tekrarlamayın. Başka bir model seçmeden önce GET /v1/models ile işlem ve Delivery kullanılabilirliğini kontrol edin. Benzer adlar kullanılabilirliği kanıtlamaz; doğrulanmamış alternatifler listelenmez.
Bazı OpenAI uyumlu hatalar isteğe bağlı did_you_mean, suggestions, alternatives, hint, retryable veya retry_after alanlarını içerir. Bkz: Ajanların işlem yapabileceği hatalar.
Bir istek Official rotasından geçtiyse ve upstream hizmeti isteğin kendisini reddettiyse (örneğin kabul etmediği bir girdi ya da içerik politikası kararı), hata ayrıca upstream içerir: upstream'in bildirdiği haliyle message, bilindiğinde de code ve source (upstream hizmetinin adı). Anthropic Messages ve Gemini hataları aynı nesneyi kendi error nesnelerinin içinde taşır. Karar vermeye code ve type üzerinden devam edin; upstream.code değerlerini upstream hizmeti belirler ve değişebilir.
Yeniden deneme kararları
| Hata | Aynı istek tekrarlanmalı mı? |
|---|---|
400, 401, 402, 403, 404, 413 | Hayır. İsteği, kimlik bilgilerini, bakiyeyi, izinleri veya girdiyi değiştirin. |
429 | Evet, sunucu tarafından sağlanan gecikmeden sonra. |
500–504 | Yalnızca retryable: true olduğunda yeniden deneyin; retry_after değerine ve deneme sınırına uyun |
| Yanıt gelmeden bağlantı koptu | Bazen. Oluşturma işlemleri için, bir görevin veya yan etkinin zaten var olup olmadığını kontrol edin. |
| Çıktı geldikten sonra akış kesildi | Bunu tam bir yanıt olarak adlandırmayın. Tekrarlamak farklı bir çıktı veya ikinci bir ücretlendirme oluşturabilir. |
Görüntü, video, müzik, 3D ve Worlds oluşturma işlemleri için, görev ID'sini döndüğü anda kaydedin. Bir oluşturma isteği zaman aşımına uğrarsa, başka bir oluşturma isteği göndermeden önce görev kaydını kontrol edin.
Request ID'yi saklayın
Yanıt başlıkları, izleme (tracing) için bir Request ID içerir. Bunu endpoint, model, zaman ve kendi kullanıcı veya iş ID'nizle birlikte kaydedin. Asenkron işler için, mevcut olduğunda task_id ve billing_transaction_id değerlerini de kaydedin.
Destek ekibiyle iletişime geçerken, bu ID'leri ve sansürlenmiş bir örneği ekleyin. Asla API anahtarlarını, yönetim token'larını, özel medyayı, imzalı URL'leri veya tam özel istemleri (prompts) göndermeyin.