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 tekrarlamayın |
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 ya da hesap kısıtlanmış | Anahtarın izinlerini veya modeli değiştirin ya da destek ekibiyle iletişime geçin |
404 | Kaynak mevcut değil veya artık erişilemiyor | ID'yi ve onu oluşturan API anahtarını kontrol edin |
409 | Idempotency-Key zaten kullanılmış: farklı bir istek gövdesiyle (idempotency_conflict) veya TokenLab'in sonucunu döndüremediği bir istek için (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab isteği tekrar çalıştırmadı | Yeni bir istek için yeni bir anahtar kullanın. Aynı anahtarla tekrar deneyip denememeye karar vermek için Idempotency key ile güvenli bir şekilde yeniden deneyin bölümüne bakın |
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 | Hizmet kullanılamıyor veya ağ hatası | Yalnızca retryable değeri true olduğunda yeniden deneyin; retry_after süresine uyun ve deneme sayısını sınırlayın |
Yaygın hata kodları
| Kod | Anlamı | Ne değiştirilmeli |
|---|---|---|
invalid_api_key | API anahtarı eksik, geçersiz, aktif değil veya iptal edilmiş | Authorization başlığını ve anahtar değerini kontrol edin |
expired_api_key | Anahtarın süresi dolmuş | 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şmış | O 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 |
user_suspended, account_restricted | HTTP 403. Hesap API'yi kullanamaz | Request ID ile destek ekibiyle iletişime geçin |
invalid_delivery_policy | HTTP 400. X-TokenLab-Delivery-Policy başlığı auto, verified veya official değil | Bu üç değerden birini gönderin veya başlığı kaldırın |
model_not_found | Model ID bilinmiyor veya mevcut değil | /v1/models endpoint'ini 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 |
missing_required_parameter | Gerekli bir alan eksik. param bunu belirtir, örneğin varsayılan modeli olmayan ses ve görüntü isteklerindeki model alanı | param tarafından belirtilen alanı gönderin |
invalid_value | Bir alan, modelin kabul etmediği bir değere sahip, örneğin bir reasoning_effort değeri. Mesaj, kabul edilen değerleri listeler | Listelenen değerlerden birini kullanın |
invalid_response_format_type | HTTP 400. response_format bir nesnedir ancak kullanılabilir bir type içermiyor veya bu endpoint'in kabul etmediği bir type içeriyor. param değeri response_format | response_format.type değerini text, json_object veya json_schema olarak ayarlayın; json_schema kullanıyorsanız json_schema.name ve json_schema.schema alanlarını da gönderin |
invalid_image_url | TokenLab bir görüntü URL'sini kullanamıyor: geçerli bir HTTP(S) URL'si veya görüntü veri URI'si değil ya da görüntü sunucusu görüntüyü döndürmedi. param alanı belirtir | Herkese açık bir HTTPS görüntü URL'si veya desteklenen bir veri URI'si gönderin |
unsupported_model_capability | Seçilen Delivery katmanının hiçbir rotası; işlem, resolution, aspect_ratio, duration, bir girdi medya alanı, web_search_options veya max_tokens gibi bir istek parametresini desteklemiyor. Mesaj, eşleşmeyen her parametreyi ve model bunları yayınladığında desteklenen değerleri belirtir | Parametreyi kaldırın veya değiştirin ya da başka bir Delivery katmanı veya model seçin; isteği değiştirmeden tekrarlamayın |
unpriceable_selection | Video isteği, fiyatlandırmanın bağlı olduğu bir seçiciyi dışarıda bırakıyor, bu nedenle TokenLab fiyatlandırma yapamıyor. param seçiciyi belirtir | param tarafından belirtilen alanı ayarlayın |
model_pricing_unavailable | HTTP 503. İstek geçerli ancak TokenLab, isteğin kullanabileceği rotalarda bu model ve işlem kombinasyonunu fiyatlandıramıyor. İstekten ücret alınmadı ve retryable değeri false | İsteği değiştirmeden tekrarlamayın; başka bir model veya işlem seçin ya da Request ID ile destek ekibiyle iletişime geçin |
idempotency_conflict | HTTP 409. Idempotency-Key farklı bir isteğe ait. TokenLab bu isteği çalıştırmadı | Yeni bir anahtarla yeni bir istek gönderin |
idempotency_replay_unavailable | HTTP 409. Idempotency-Key zaten kullanılmış ve TokenLab'in bunun için döndüreceği bir sonuç yok. TokenLab bu isteği tekrar çalıştırmadı | İlk istek hala çalışıyor olabilirse, bekleyin ve aynı anahtarla tekrar deneyin. Aksi takdirde yeni bir anahtar gönderin. Idempotency key ile güvenli bir şekilde yeniden deneyin bölümüne bakın |
idempotent_response_not_replayable | HTTP 409. Idempotency-Key, görevi zaten bitmiş bir oluşturma isteğine ait ve TokenLab orijinal oluşturma yanıtını döndüremiyor. Yanıt gövdesinin en üst seviyesi, error yanında task_id içerir. TokenLab bu isteği tekrar çalıştırmadı | İsteği bu anahtarla tekrarlamayın. Yalnızca yeni bir görev istiyorsanız yeni bir anahtar gönderin |
rate_limit_exceeded | Mevcut pencerede çok fazla istek gönderildi | Retry-After süresini bekleyin |
all_channels_failed | Seçilen model bu isteği karşılayamıyor | Yalnızca retryable değeri true olduğunda yeniden deneyin; retry_after süresine uyun ve deneme sayısını sınırlayın |
timeout_error | İstek zamanında bitmedi | Yalnızca işlemin tekrarlanması güvenli olduğunda yeniden deneyin |
503 all_channels_failed veya 503 delivery_tier_unavailable hatası her zaman geçici bir kesinti anlamına gelmez. İstenen işlemin seçilen Delivery katmanında arzı yoksa, retryable değeri false olur ve retry_after atlanır. Aynı isteği tekrarlamayın. Başka bir model seçmeden önce GET /v1/models ile işlem ve Delivery uygunluğunu kontrol edin. Benzer isimler uygunluğu kanıtlamaz; doğrulanmamış alternatifler atlanmıştır.
Bazı OpenAI uyumlu hatalar isteğe bağlı did_you_mean, suggestions, alternatives, hint, retryable veya retry_after alanlarını içerir. Ajanların işlem yapabileceği hatalar bölümüne bakın.
Bir istek Official rotada çalıştırıldığında ve yukarı akış (upstream) hizmeti isteğin kendisini reddettiğinde (örneğin kabul etmediği bir girdi veya içerik politikası kararı), hata ayrıca upstream bilgisini de taşır: bildirildiği şekliyle yukarı akışın message değeri, artı bilindiğinde code ve source (yukarı akış hizmet adı). Anthropic Messages ve Gemini hataları, kendi error nesneleri içinde aynı nesneyi taşır. code ve type üzerinden dallanmaya devam edin; upstream.code değerleri yukarı akış hizmeti tarafından tanımlanır 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 değeri true olduğunda yeniden deneyin; retry_after süresine uyun ve deneme sayısını sınırlayın |
| Herhangi bir yanıt gelmeden bağlantı kapandı | Evet, istek Idempotency key ile güvenli bir şekilde yeniden deneyin bölümünde listelenmişse ve bir Idempotency-Key değerine sahipse: aynı anahtar ve gövde ile tekrar gönderin. Aksi takdirde, önce 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, orijinal görevi almak için aynı Idempotency-Key ve gövde ile tekrar gönderin. Bir anahtar olmadan, başka bir oluşturma isteği göndermeden önce görev kaydını kontrol edin.
Idempotency key ile güvenli bir şekilde yeniden deneyin
Bir zaman aşımı veya kapalı bağlantı, TokenLab'in isteği çalıştırıp çalıştırmadığını size söylemez. Aşağıda listelenen isteklere bir Idempotency-Key başlığı ekleyin. Bu durumda, aynı isteğin yeniden denenmesi onu ikinci kez çalıştıramaz veya ücretlendiremez.
- Her işlem için yeni ve benzersiz bir değer kullanın, örneğin bir UUID. Bir anahtar 255 karaktere kadar olabilir. TokenLab daha uzun bir anahtarı görmezden gelir ve bu durumda isteğin idempotency koruması olmaz: yeniden deneme çalışır ve tekrar ücretlendirilir.
POST /v1/messages/batchesfarklıdır: 256 karakterden uzun bir anahtarı400hatasıyla reddeder. - İsteği göndermeden önce anahtarı kendi iş kaydınızla birlikte saklayın.
- Yeniden denediğinizde, aynı API anahtarını, aynı
Idempotency-Keydeğerini ve aynı gövdeyi gönderin. idempotency_replay_unavailablehatası içeren409dışındaki herhangi bir yanıttan sonra, o anahtarı tekrar kullanmayın. Herhangi bir yeni denemeyi yeni bir anahtarla gönderin.- SDK yeniden denemelerini kapatın (
max_retries=0), böylece kodunuz bir anahtarın ne zaman yeniden kullanılacağına karar verebilir.
Başlık olmadan, her yeniden deneme yeni bir istektir.
Görev oluşturan istekler
Bu oluşturma istekleri Idempotency-Key kabul eder:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generationsvePOST /v1/worlds/generations- Bir görev döndürdüklerinde
POST /v1/images/generationsvePOST /v1/images/edits "background": trueilePOST /v1/responsesPOST /v1/messages/batches
Bir oluşturma isteği zaman aşımına uğrarsa, değişiklik yapmadan tekrar gönderin. TokenLab orijinal oluşturma isteğinin sonucunu döndürür ve ikinci bir görev oluşturmaz, göndermez veya ücretlendirmez. Genellikle sonuç, aynı id değerine sahip orijinal görevdir (Responses için orijinal yanıt nesnesi) ve onu sorgulamaya devam edersiniz. Video, müzik, 3D, Worlds ve görüntü görevleri için sonuç, ilk oluşturma isteği başarısız olduğunda orijinal hata da olabilir. Böyle bir görev zaten bittiyse ve TokenLab'in saklanan bir oluşturma yanıtı yoksa, yeniden deneme idempotent_response_not_replayable koduyla 409 döndürür ve yanıt gövdesinin en üst seviyesi task_id içerir.
TokenLab'in zaten kabul ettiği bir anahtarla farklı bir gövde gönderirseniz, TokenLab isteği reddeder ve görev oluşturmaz. Video, müzik, 3D ve Worlds oluşturma istekleri idempotency_conflict koduyla 409 döndürür. Message Batches, conflict_error hata tipiyle 409 döndürür. Görüntü görevleri ve background: true içeren Responses istekleri için bu durumdaki durum kodu ve hata kodu garanti edilmez. İsteği aynı anahtarla tekrar denemeyin.
Chat Completions, Responses ve Messages
POST /v1/chat/completions, background içermeyen POST /v1/responses ve POST /v1/messages, belirli bir anahtarla bir isteği yalnızca bir kez çalıştırır. Aynı anahtarla yapılan bir yeniden deneme şu sonuçlardan birini alır:
| Durum | Sonuç |
|---|---|
| İlk istek hala çalışıyor | idempotency_replay_unavailable koduyla 409 |
| İlk istek istemciniz bağlantıyı kestikten sonra bitti. İstek akış (stream) olarak gönderilmedi, sonuç 1 MB veya daha küçük ve aynı gövdeyle 24 saat içinde tekrar deniyorsunuz | Idempotent-Replayed: true başlığı ve orijinal yanıt gövdesiyle 200. TokenLab isteği tekrar çalıştırmaz veya ücretlendirmez |
| Anahtar başka bir şekilde kullanıldı, örneğin: sonucu aldınız, istek akış olarak gönderildi, sonuç 1 MB'tan büyüktü veya 24 saatten fazla zaman geçti | idempotency_replay_unavailable koduyla 409 |
| Gövde ilk istekten farklı | 409, genellikle idempotency_conflict koduyla. Bazı istekler idempotency_replay_unavailable döndürür |
Her iki kodla da gelen 409, TokenLab'in isteği tekrar çalıştırmadığı anlamına gelir. Anahtarlı bir akış isteği iki kez çalışamaz, ancak TokenLab çıktısını tekrar gönderemez.
Bu örnek, zaman aşımına uğrayan bir Chat Completions isteğini, sonuç alana kadar aynı anahtarla yeniden dener:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Bu anahtarı iş kaydınızla saklayın.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # Yanıt yok: aynı anahtar ve gövde ile yeniden deneyin.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# İlk deneme hala çalışıyor olabilir. Daha sonraki bir yeniden deneme sonucunu döndürür.
raise RuntimeError(f"No result for Idempotency-Key {key}")Son deneme hala idempotency_replay_unavailable döndürürse, TokenLab bu sonucu döndüremez. İsteği yalnızca ikinci bir çalıştırma ve ikinci bir ücretlendirme kabul edilebilir ise yeni bir anahtarla gönderin.
Request ID'yi saklayın
Yanıt başlıkları, izleme için bir Request ID içerir. Bunu endpoint, model, zaman ve kendi kullanıcı veya iş ID'nizle birlikte saklayın. Asenkron çalışmalar için, mevcut olduğunda task_id ve billing_transaction_id değerlerini de saklayın.
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.