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ı

DurumAnlamıTipik eylem
400Bir alan, model ID veya girdi geçersizİsteği düzeltin; değiştirmeden tekrarlamayın
401API anahtarı eksik, geçersiz, süresi dolmuş veya iptal edilmişAnahtarı değiştirin
402Bakiye veya API anahtarı limiti çok düşükBakiye yükleyin, limiti artırın veya isteği azaltın
403Bu 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
404Kaynak mevcut değil veya artık erişilemiyorID'yi ve onu oluşturan API anahtarını kontrol edin
409Idempotency-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ükGirdiyi belgelenen model veya endpoint limitine göre azaltın
429İstek limitine ulaşıldıRetry-After süresini bekleyin
500–504Hizmet 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ı

KodAnlamıNe değiştirilmeli
invalid_api_keyAPI anahtarı eksik, geçersiz, aktif değil veya iptal edilmişAuthorization başlığını ve anahtar değerini kontrol edin
expired_api_keyAnahtarın süresi dolmuşAktif bir anahtar oluşturun veya seçin
insufficient_balanceHesap bakiyesi isteği karşılayamıyorBakiye ekleyin, isteği azaltın veya daha düşük fiyatlı bir model seçin
quota_exceededAPI anahtarı kendi limitine ulaşmışO anahtarın limitini artırın veya yetkili başka bir anahtar kullanın
model_not_allowedAnahtar istenen modeli kullanamazAnahtarın model listesini güncelleyin veya izin verilen bir model seçin
user_suspended, account_restrictedHTTP 403. Hesap API'yi kullanamazRequest ID ile destek ekibiyle iletişime geçin
invalid_delivery_policyHTTP 400. X-TokenLab-Delivery-Policy başlığı auto, verified veya official değilBu üç değerden birini gönderin veya başlığı kaldırın
model_not_foundModel ID bilinmiyor veya mevcut değil/v1/models endpoint'ini okuyun ve güncel bir model ID kullanın
context_length_exceededGirdi, modelin kabul ettiğinden daha uzunGeçmişi kaldırın veya daha büyük bir bağlam penceresine sahip bir model seçin
missing_required_parameterGerekli 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_valueBir alan, modelin kabul etmediği bir değere sahip, örneğin bir reasoning_effort değeri. Mesaj, kabul edilen değerleri listelerListelenen değerlerden birini kullanın
invalid_response_format_typeHTTP 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_formatresponse_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_urlTokenLab 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ı belirtirHerkese açık bir HTTPS görüntü URL'si veya desteklenen bir veri URI'si gönderin
unsupported_model_capabilitySeç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 belirtirParametreyi 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_selectionVideo 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 belirtirparam tarafından belirtilen alanı ayarlayın
model_pricing_unavailableHTTP 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_conflictHTTP 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_unavailableHTTP 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_replayableHTTP 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_exceededMevcut pencerede çok fazla istek gönderildiRetry-After süresini bekleyin
all_channels_failedSeçilen model bu isteği karşılayamıyorYalnı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 bitmediYalnı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ı

HataAynı istek tekrarlanmalı mı?
400, 401, 402, 403, 404, 413Hayır. İsteği, kimlik bilgilerini, bakiyeyi, izinleri veya girdiyi değiştirin.
429Evet, sunucu tarafından sağlanan gecikmeden sonra.
500–504Yalnı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ış kesildiBunu 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/batches farklıdır: 256 karakterden uzun bir anahtarı 400 hatası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-Key değerini ve aynı gövdeyi gönderin.
  • idempotency_replay_unavailable hatası içeren 409 dışı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/generations ve POST /v1/worlds/generations
  • Bir görev döndürdüklerinde POST /v1/images/generations ve POST /v1/images/edits
  • "background": true ile POST /v1/responses
  • POST /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:

DurumSonuç
İlk istek hala çalışıyoridempotency_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 deniyorsunuzIdempotent-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çtiidempotency_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.

From a request to an investigation and support

Bu sayfada