Moknah Dokumen
Mulai gratis
Referensi API

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

HTTP: 401 WSS: 4001 / 4002

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

HTTP: 402 WSS: JSON di tengah streaming

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

HTTP: 409 / 429 WSS: 4290

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

HTTP: 400 WSS: JSON di tengah streaming

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}`);
    }
});
Praktik Terbaik: Exponential Backoff

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.

Dukungan API

Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.