Moknah 문서
무료로 시작하기
API 레퍼런스

오류

API 오류 응답, WebSocket 종료 코드 및 처리 방법 이해하기

REST API 오류 형식 (HTTP)

표준 HTTP 엔드포인트에서 오류가 발생하면 API는 다음 구조의 JSON 응답을 반환합니다:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "사람이 읽을 수 있는 오류 설명",
        "details": {
          // 추가 컨텍스트 (오류 유형에 따라 다름)
        }
    }
}

WebSocket 오류 형식 (WSS)

WebSocket은 오류를 다르게 처리합니다. 오류는 초기 연결 핸드셰이크 중에 발생하거나 오디오가 생성되는 스트리밍 도중에 발생할 수 있습니다.

  • 치명적 오류: 특정 종료 코드(예: 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: 분당 요청 수(RPM) 60회 한도를 초과했습니다.
  • 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) 오류의 경우 지수 백오프를 구현하세요. 1초, 2초, 4초 순으로 대기 시간을 늘립니다. 이렇게 하면 API 과부하를 방지하고 잠금이 해제된 후 요청이 성공적으로 처리되도록 보장할 수 있습니다.

API 지원

API 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.