Moknah دستاویزات
مفت شروع کریں
API ریفرنس

خرابیاں

API کے ایرر جوابات، WebSocket کلوز کوڈز، اور انہیں ہینڈل کرنے کا طریقہ سمجھنا

REST API ایرر فارمیٹ (HTTP)

جب کسی معیاری HTTP اینڈ پوائنٹ پر کوئی خرابی پیش آتی ہے، تو API درج ذیل ساخت کے ساتھ JSON جواب واپس کرتا ہے:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "انسانوں کے پڑھنے کے قابل خرابی کی تفصیل",
        "details": {
          // اضافی سیاق و سباق (خرابی کی قسم کے لحاظ سے مختلف ہوتا ہے)
        }
    }
}

WebSocket ایرر فارمیٹ (WSS)

WebSockets ایررز کو مختلف طریقے سے ہینڈل کرتے ہیں۔ ایررز ابتدائی کنکشن ہینڈ شیک کے دوران، یا آڈیو بننے کے دوران سٹریم کے بیچ میں پیش آ سکتے ہیں۔

  • شدید ایررز: کنکشن ایک مخصوص کلوز کوڈ (مثلاً 4290) کے ساتھ منقطع کر دیا جاتا ہے۔
  • سٹریم کے دوران ایررز: سرور بند ہونے سے پہلے ایک سادہ JSON ایرر فریم بھیجتا ہے: {"error": "سٹریم کے دوران ناکافی کریڈٹس"}

سٹیٹس کوڈز اور کلوز کوڈز

HTTP سٹیٹس کوڈز (REST)

حیثیت مطلب تفصیل
200 ٹھیک ہے درخواست کامیاب رہی
400 غلط درخواست درخواست کے پیرامیٹرز غلط ہیں یا درخواست کی ساخت درست نہیں
401 غیر مجاز API کلید غائب ہے یا غلط ہے
402 ادائیگی درکار ہے درخواست مکمل کرنے کے لیے کافی کریڈٹس نہیں ہیں
403 ممنوع API کلید کو اس عمل کی اجازت نہیں ہے
404 نہیں ملا درخواست کردہ ریسورس موجود نہیں ہے
409 تصادم درخواست موجودہ صورتحال سے متصادم ہے (مثلاً بیک وقت HTTP درخواست)
429 بہت زیادہ درخواستیں ریٹ کی حد سے تجاوز ہو گیا
500 اندرونی سرور ایرر ہماری طرف سے کچھ غلط ہو گیا

WebSocket کلوز کوڈز (WSS)

کوڈ قسم تفصیل
1000 معمول کی بندش سٹریم کامیابی سے مکمل ہو گئی۔
3011 جنریشن ایرر اپ سٹریم API پر آڈیو جنریشن ناکام ہو گئی۔ درخواست دوبارہ کوشش کریں۔
4001 تصدیق غائب ہے ہینڈ شیک کے دوران Authorization ہیڈر میں کوئی API کلید فراہم نہیں کی گئی۔
4002 تصدیق ناکام ہو گئی غلط کلید، غیر فعال اکاؤنٹ، ناکافی ابتدائی کریڈٹس، یا IP پابندی۔
4290 بیک وقت کنکشن کی حد آپ کے پاس پہلے سے ہی ایک فعال TTS WebSocket کنکشن موجود ہے۔ حد فی صارف 1 ہے۔

عام ایرر کے منظر نامے

1. غیر مجاز / تصدیق ناکام ہو گئی

HTTP: 401 WSS: 4001 / 4002

API کلید کے غائب یا غلط ہونے، یا IP وائٹ لسٹ کی پابندیوں کی وجہ سے تصدیق ناکام ہو گئی۔

عام وجوہات:

  • Authorization: Bearer ہیڈر موجود نہیں ہے
  • API کلید کا فارمیٹ غلط ہے یا کلید منسوخ کر دی گئی ہے
  • ایسے IP ایڈریس سے کنیکٹ ہو رہا ہے جو آپ کی کلید کی وائٹ لسٹ میں شامل نہیں ہے

2. ناکافی کریڈٹس

HTTP: 402 WSS: مڈ اسٹریم JSON

آپ کے اکاؤنٹ میں اس درخواست کو مکمل کرنے کے لیے کافی کریڈٹس نہیں ہیں۔

  • HTTP: آڈیو تیار کرنے سے فوراً پہلے ناکام ہو جاتا ہے۔
  • WebSocket: اگر اسٹریم کے دوران آپ کے کریڈٹس ختم ہو جائیں تو سرور بھیجتا ہے {"error": "سٹریم کے دوران ناکافی کریڈٹس"} اور کنکشن کو صاف طور پر بند کر دیتا ہے۔ کریڈٹس ختم ہونے سے پہلے تیار کیا گیا آڈیو پھر بھی فراہم کیا جائے گا۔

3. بیک وقت درخواستیں اور ریٹ کی حدود

HTTP: 409 / 429 WSS: 4290

منصفانہ استعمال کو یقینی بنانے کے لیے Moknah ایک وقت میں فی صارف ایک درخواست پر کارروائی کرتا ہے۔

  • HTTP 409: آپ کے اکاؤنٹ سے ایک اور درخواست پر پہلے ہی کارروائی ہو رہی ہے۔ اس کے مکمل ہونے کا انتظار کریں۔
  • HTTP 429: آپ نے فی منٹ 60 درخواستوں (RPM) کی حد عبور کر لی ہے۔
  • WSS 4290: آپ نے دوسرا WebSocket کنکشن کھولنے کی کوشش کی جبکہ آپ کا پہلا کنکشن ابھی تک فعال تھا۔

4. غلط درخواست / خراب ڈیٹا

HTTP: 400 WSS: مڈ اسٹریم JSON

درخواست کے پیرامیٹرز غلط ہیں، یا آپ نے ٹیکسٹ چنک کی حدود کو عبور کر لیا ہے۔

  • HTTP: مطلوبہ فیلڈز (text, voice_id) غائب ہیں۔
  • WebSocket: 2,000 حروف سے بڑا ٹیکسٹ چنک بھیجنے کا نتیجہ یہ نکلے گا {"error": "چنک بہت بڑا ہے۔ فی چنک زیادہ سے زیادہ 2000 حروف ہو سکتے ہیں۔"}.

کوڈ میں خرابیوں سے نمٹنا

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  # آڈیو بائٹس
    elif response.status_code == 402:
        raise Exception("ناکافی کریڈٹس")
    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)  # دوبارہ کوشش کریں
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # دوبارہ کوشش کریں
    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}`);
    }
});
بہترین طریقہ کار: Exponential Backoff

429 (HTTP)، 409 (HTTP)، اور 4290 (WSS) خرابیوں کے لیے، exponential backoff نافذ کریں: پہلے 1 سیکنڈ انتظار کریں، پھر 2 سیکنڈ، پھر 4 سیکنڈ، وغیرہ۔ یہ API پر زیادہ بوجھ پڑنے سے روکتا ہے اور اس بات کو یقینی بناتا ہے کہ لاک ختم ہوتے ہی آپ کی درخواست کامیاب ہو جائے۔

API سپورٹ

API سے متعلق سوالات یا مسائل کے لیے، ہم سے یہاں رابطہ کریں api@moknah.io.