Yaygın bağlantı hataları ve bunları düzeltme yolları

Neredeyse tüm bağlantı sorunları dört şeye indirgenir: adres, anahtar, model kimliği ve bakiye. Aşağıdaki hızlı kontrolle başlayın, ardından durum kodunuzu bulun. Burada alıntılanan yanıt gövdeleri API'nin gerçek yanıtlarıdır (Ekim 2026).

Hızlı kontrol#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

İlk komut başarısız olursa, neden sizin tarafınızdaki ağ, adresteki bir yazım hatası — ya da hizmetin geçici olarak kullanılamıyor olması olabilir. Yalnızca ikincisi başarısız olursa, aşağıdan durum koduna bakın. İkisi de çalışıyor ama aracınız çalışmıyorsa, aracın ayarlarını bu iki komutla karşılaştırın.

401 — Geçersiz API anahtarı#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Anthropic tarzı istemciler aynı hatayı kendi formatlarında alır:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Nedenler:

• anahtar eksik bir karakter, boşluk veya tırnak işaretiyle kopyalanmış;
• anahtar panelde döndürülmüş — eskisi artık çalışmıyor;
• CheapTokens anahtarı yerine başka bir hizmetin (örneğin OpenAI) anahtarı ayarlanmış;
• ortam değişkeni bu terminalde boş: echo ${#CHEAPTOKENS_API_KEY} uzunluğunu yazdırır.

Panel bir anahtarı yalnızca bir kez gösterir. Kaybolduysa, yeni bir tane almak için Rotate düğmesine basın ve kullanıldığı her yerde güncelleyin.

402 — boş bakiye veya istekte anahtar yok#

API 402'yi iki farklı durumda döndürür:

1. Bakiye tükenmiş. İstekler bakiyeden ödenir; bittiğinde anahtar duraklatılır. Panelden bakiye yükleyin ve istekler yeniden geçer.
2. İstekte hiç anahtar yok. Authorization başlığı (veya Anthropic tarzı istemciler için x-api-key) eksikse, API insufficient_funds türüyle 402 yanıtı verir. Aracınızın anahtarı gerçekten gönderdiğini kontrol edin: OpenAI tarzı Authorization: Bearer <key>.

404 — yanlış adres#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

Yolda bir yazım hatası var — burada completions yerine completion. Diğer yaygın nedenler:

• Temel URL'de /v1 yok. OpenAI tarzı istemciler https://api.cheaptokens.dev/v1 gerektirir. /v1 olmadan istek API'yi ıskalar ve JSON yerine düz bir HTML 404 sayfası alırsınız.
• /v1 iki kez. Bazı istemciler /v1 kendileri ekler; o zaman temel URL kök olmalıdır, https://api.cheaptokens.dev. Anthropic tarzı istemciler her zaman kök adresi kullanır.

400 — model bulunamadı#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

Model kimliği, eğik çizgiden önceki önek dahil tam kimlik olmalıdır: deepseek-v4-flash değil, deepseek-ai/DeepSeek-V4-Flash-0731. Büyük veya küçük harf fark etmez. Hata mesajı kullanılabilir kimlikleri listeler ve tam liste her zaman GET /v1/models adresindedir.

400 ayrıca hatalı biçimlendirilmiş bir istek gövdesi için de döner — örneğin boş bir messages dizisi (messages field is required and must be a non-empty array) veya role olmayan bir mesaj.

413 — istek çok büyük#

İstek gövdesi 16 MB ile sınırlıdır. Ajanlar bağlama dev dosyalar veya günlükler koyarak bu sınıra takılabilir. Yalnızca modelin ihtiyaç duyduğu kısımları gönderin ve uzun araç çıktısını kısaltın.

429 — çok fazla istek#

429 alırsanız, yavaşlayın. Yanıt, beklenecek saniye sayısını içeren bir Retry-After başlığı içerir. Resmi OpenAI SDK'ları otomatik olarak yeniden dener (max_retries); kendi kodunuzda, bir sonraki denemeden önce Retry-After bekleyin.

503 — model geçici olarak kullanılamıyor#

Bir model geçici olarak kullanılamayabilir; API o zaman model_unavailable türüyle 503 yanıtı verir ve sitedeki model kartı "geçici olarak kullanılamıyor" gösterir. Daha sonra yeniden deneyin veya model alanını başka bir modele çevirin — anahtar ve adres aynı kalır.

Uzun beklemeler ve zaman aşımları#

zai-org/GLM-5.3-Flash gibi akıl yürütme modelleri yanıtlamadan önce düşünür, bu yüzden ilk token biraz zaman alabilir. Akış kullanın veya istemci zaman aşımını artırın — örneğin OpenAI SDK'da timeout=120.