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.