Error
Memahami respons error API, kode penutupan WebSocket, dan cara menanganinya
Format Error REST API (HTTP)
Saat terjadi error pada endpoint HTTP standar, API mengembalikan respons JSON dengan struktur berikut:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Deskripsi error yang mudah dibaca",
"details": {
// Konteks tambahan (bervariasi menurut jenis error)
}
}
}
Format Kesalahan WebSocket (WSS)
WebSocket menangani kesalahan secara berbeda. Kesalahan dapat terjadi selama jabat tangan (handshake) koneksi awal, atau di tengah streaming saat audio sedang dibuat.
- Kesalahan Fatal: Koneksi diputus dengan Kode Penutupan tertentu (mis., 4290).
- Kesalahan di Tengah Streaming: Server mengirimkan frame kesalahan JSON datar sebelum menutup:
{"error": "Kredit tidak mencukupi selama streaming"}
Kode Status & Kode Penutupan
Kode Status HTTP (REST)
| Status | Arti | Deskripsi |
|---|---|---|
200 |
OK | Permintaan berhasil |
400 |
Permintaan Buruk | Parameter permintaan tidak valid atau format permintaan salah |
401 |
Tidak Diizinkan | Kunci API hilang atau tidak valid |
402 |
Pembayaran Diperlukan | Kredit tidak cukup untuk menyelesaikan permintaan |
403 |
Dilarang | Kunci API tidak memiliki izin untuk tindakan ini |
404 |
Tidak Ditemukan | Sumber daya yang diminta tidak ada |
409 |
Konflik | Permintaan bertentangan dengan status saat ini (mis., permintaan HTTP bersamaan) |
429 |
Terlalu Banyak Permintaan | Batas laju terlampaui |
500 |
Kesalahan Server Internal | Terjadi kesalahan di pihak kami |
Kode Penutupan WebSocket (WSS)
| Kode | Jenis | Deskripsi |
|---|---|---|
1000 |
Penutupan Normal | Streaming berhasil diselesaikan. |
3011 |
Kesalahan Pembuatan | Pembuatan audio gagal pada API hulu. Coba lagi permintaan tersebut. |
4001 |
Autentikasi Hilang | Tidak ada kunci API yang diberikan di header Authorization selama jabat tangan (handshake). |
4002 |
Autentikasi Gagal | Kunci tidak valid, akun tidak aktif, kredit awal tidak mencukupi, atau pembatasan IP. |
4290 |
Batas Konkurensi | Anda sudah memiliki koneksi WebSocket TTS yang aktif. Batasnya adalah 1 per pengguna. |
Skenario Kesalahan Umum
1. Tidak Diizinkan / Autentikasi Gagal
Autentikasi gagal karena kunci API hilang atau tidak valid, atau pembatasan daftar putih IP.
Penyebab umum:
- Header Authorization: Bearer tidak ada
- Format kunci API tidak valid atau kunci telah dicabut
- Menghubungkan dari alamat IP yang tidak ada dalam daftar putih kunci Anda
2. Kredit Tidak Mencukupi
Akun Anda tidak memiliki cukup kredit untuk menyelesaikan permintaan ini.
- HTTP: Gagal seketika sebelum menghasilkan audio.
- WebSocket: Jika Anda kehabisan kredit di tengah streaming, server akan mengirimkan
{"error": "Kredit tidak mencukupi selama streaming"}dan menutup koneksi dengan rapi. Audio yang dihasilkan sebelum kehabisan kredit akan tetap dikirimkan.
3. Konkurensi & Batas Laju
Moknah memproses satu permintaan per pengguna pada satu waktu untuk memastikan penggunaan yang wajar.
- HTTP 409: Permintaan lain dari akun Anda sedang diproses. Tunggu hingga selesai.
- HTTP 429: Anda melampaui batas 60 Permintaan Per Menit (RPM).
- WSS 4290: Anda mencoba membuka koneksi WebSocket kedua saat koneksi pertama masih aktif.
4. Permintaan Tidak Valid / Data Buruk
Parameter permintaan tidak valid, atau Anda melampaui batas potongan teks.
- HTTP: Kolom wajib diisi tidak ada (text, voice_id).
- WebSocket: Mengirim potongan teks lebih dari 2.000 karakter akan menghasilkan
{"error": "Potongan terlalu besar. Maksimum 2000 karakter per potongan."}.
Menangani Kesalahan dalam Kode
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 # Byte audio
elif response.status_code == 402:
raise Exception("Kredit tidak mencukupi")
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) # Coba Lagi
elif response.status_code == 409:
time.sleep(5)
return generate_speech(text, voice_id, api_key) # Coba Lagi
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}`);
}
});
Untuk kesalahan 429 (HTTP), 409 (HTTP), dan 4290 (WSS), terapkan exponential backoff: tunggu 1 dtk, lalu 2 dtk, lalu 4 dtk, dst. Ini mencegah API kelebihan beban dan menjamin permintaan Anda akan berhasil setelah kunci terbuka.
Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.