خرابیاں
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. غیر مجاز / تصدیق ناکام ہو گئی
API کلید کے غائب یا غلط ہونے، یا IP وائٹ لسٹ کی پابندیوں کی وجہ سے تصدیق ناکام ہو گئی۔
عام وجوہات:
- Authorization: Bearer ہیڈر موجود نہیں ہے
- API کلید کا فارمیٹ غلط ہے یا کلید منسوخ کر دی گئی ہے
- ایسے IP ایڈریس سے کنیکٹ ہو رہا ہے جو آپ کی کلید کی وائٹ لسٹ میں شامل نہیں ہے
2. ناکافی کریڈٹس
آپ کے اکاؤنٹ میں اس درخواست کو مکمل کرنے کے لیے کافی کریڈٹس نہیں ہیں۔
- HTTP: آڈیو تیار کرنے سے فوراً پہلے ناکام ہو جاتا ہے۔
- WebSocket: اگر اسٹریم کے دوران آپ کے کریڈٹس ختم ہو جائیں تو سرور بھیجتا ہے
{"error": "سٹریم کے دوران ناکافی کریڈٹس"}اور کنکشن کو صاف طور پر بند کر دیتا ہے۔ کریڈٹس ختم ہونے سے پہلے تیار کیا گیا آڈیو پھر بھی فراہم کیا جائے گا۔
3. بیک وقت درخواستیں اور ریٹ کی حدود
منصفانہ استعمال کو یقینی بنانے کے لیے Moknah ایک وقت میں فی صارف ایک درخواست پر کارروائی کرتا ہے۔
- HTTP 409: آپ کے اکاؤنٹ سے ایک اور درخواست پر پہلے ہی کارروائی ہو رہی ہے۔ اس کے مکمل ہونے کا انتظار کریں۔
- HTTP 429: آپ نے فی منٹ 60 درخواستوں (RPM) کی حد عبور کر لی ہے۔
- WSS 4290: آپ نے دوسرا WebSocket کنکشن کھولنے کی کوشش کی جبکہ آپ کا پہلا کنکشن ابھی تک فعال تھا۔
4. غلط درخواست / خراب ڈیٹا
درخواست کے پیرامیٹرز غلط ہیں، یا آپ نے ٹیکسٹ چنک کی حدود کو عبور کر لیا ہے۔
- 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}`);
}
});
429 (HTTP)، 409 (HTTP)، اور 4290 (WSS) خرابیوں کے لیے، exponential backoff نافذ کریں: پہلے 1 سیکنڈ انتظار کریں، پھر 2 سیکنڈ، پھر 4 سیکنڈ، وغیرہ۔ یہ API پر زیادہ بوجھ پڑنے سے روکتا ہے اور اس بات کو یقینی بناتا ہے کہ لاک ختم ہوتے ہی آپ کی درخواست کامیاب ہو جائے۔
API سے متعلق سوالات یا مسائل کے لیے، ہم سے یہاں رابطہ کریں api@moknah.io.