Hatalar

API hata yanıtlarını, WebSocket kapatma kodlarını ve bunların nasıl ele alınacağını anlamak

REST API Hata Formatı (HTTP)

Standart bir HTTP uç noktasında bir hata oluştuğunda, API aşağıdaki yapıya sahip bir JSON yanıtı döndürür:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "İnsan tarafından okunabilir hata açıklaması",
        "details": {
          // Ek bağlam (hata türüne göre değişir)
        }
    }
}

WebSocket Hata Formatı (WSS)

WebSocket’ler hataları farklı şekilde ele alır. Hatalar, ilk bağlantı el sıkışması sırasında veya sesin oluşturulduğu akış esnasında meydana gelebilir.

• Kritik Hatalar: Bağlantı, belirli bir Kapatma Kodu (ör. 4290) ile sonlandırılır.
• İşlem Sırasında Oluşan Hatalar: Sunucu, bağlantıyı kapatmadan önce düz bir JSON hata çerçevesi gönderir: {"error": "Yayın sırasında yetersiz kredi"}

Durum Kodları ve Kapatma Kodları

HTTP Durum Kodları (REST)

WebSocket Kapatma Kodları (WSS)

Yaygın Hata Senaryoları

1. Yetkisiz / Kimlik Doğrulama Başarısız

Eksik veya geçersiz API anahtarı ya da IP beyaz liste kısıtlamaları nedeniyle kimlik doğrulama başarısız oldu.

Yaygın nedenler:

• Authorization: Bearer başlığı eksik
• Geçersiz API anahtarı formatı veya anahtar iptal edilmiş
• Anahtarınızın izin verilenler listesinde yer almayan bir IP adresinden bağlanılıyor

2. Yetersiz Kredi

Hesabınızda bu isteği tamamlamak için yeterli kredi bulunmuyor.

• HTTP: Ses oluşturulmadan hemen önce başarısız oluyor.
• WebSocket: Akış sırasında krediniz biterse, sunucu gönderir {"error": "Yayın sırasında yetersiz kredi"} ve bağlantıyı düzgün bir şekilde sonlandırır. Krediler tükenmeden önce oluşturulan ses yine de iletilir.

3. Eşzamanlılık ve Hız Sınırları

Moknah, adil kullanımı sağlamak amacıyla her kullanıcı için aynı anda tek bir talebi işleme alır.

• HTTP 409: Hesabınızdan gelen başka bir istek halihazırda işleniyor. İşlemin tamamlanmasını bekleyin.
• HTTP 429: Dakikada 60 İstek (RPM) sınırını aştınız.
• WSS 4290: İlk WebSocket bağlantınız hâlâ etkinken ikinci bir WebSocket bağlantısı açmaya çalıştınız.

4. Geçersiz İstek / Hatalı Veri

İstek parametreleri geçersiz veya metin parçası sınırlarını aştınız.

• HTTP: Zorunlu alanlar (text, voice_id) eksik.
• WebSocket: 2.000 karakterden daha uzun bir metin parçası göndermek şunlara yol açacaktır: {"error": "Parça çok büyük. Parça başına maksimum 2000 karakter."}.

Kodda Hataları Ele Alma

import requests
import time

def generate_speech(text, voice_id, api_key):
    url = "https://moknah.io/api/v1/tts/generate"
    headers = {"Authorization": f"Bearer {api_key}"}

    response = requests.post(url, json={"text": text, "voice_id": voice_id}, headers=headers)

    if response.status_code == 200:
        return response.content  # Ses kesitleri
    elif response.status_code == 402:
        raise Exception("Yetersiz kredi")
    elif response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return generate_speech(text, voice_id, api_key)  # Yeniden dene
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # Yeniden dene
    else:
        raise Exception(f"API error: {response.status_code}")

async function generateSpeech(text, voiceId, apiKey) {
  const response = await fetch("https://moknah.io/api/v1/tts/generate", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ text: text, voice_id: voiceId })
  });

  if (response.ok) return await response.blob();

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") || 5;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return generateSpeech(text, voiceId, apiKey);
  }

  if (response.status === 409) {
    await new Promise(r => setTimeout(r, 5000));
    return generateSpeech(text, voiceId, apiKey);
  }

  const error = await response.json();
  throw new Error(error.error?.message || "API Error");
}

const ws = new WebSocket('wss://moknah.io/api/v1/api/v1/tts/ws/', {
    headers: { "Authorization": `Bearer ${apiKey}` }
});

// Handle Mid-Stream JSON Errors
ws.on('message', (data, isBinary) => {
    if (!isBinary) {
        const msg = JSON.parse(data.toString());
        if (msg.error) {
            console.error("Stream Error:", msg.error);
            // e.g., "Insufficient credits during stream"
        }
    }
});

// Handle Fatal Close Codes
ws.on('close', (code, reason) => {
    switch(code) {
        case 1000:
            console.log("Stream finished successfully.");
            break;
        case 4001:
        case 4002:
            console.error("Authentication failed. Check your API key.");
            break;
        case 4290:
            console.error("Concurrency limit reached. Close other active streams.");
            // Wait a few seconds before attempting to reconnect
            setTimeout(reconnect, 5000);
            break;
        case 3011:
            console.error("Upstream generation failed. Please try again.");
            break;
        default:
            console.error(`Disconnected with code ${code}`);
    }
});