Ошибки
Разбор ответов 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 |
Лимит на количество одновременных операций | У вас уже есть активное WebSocket-соединение для TTS. Ограничение — 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: Отправка фрагмента текста объемом более 2000 символов приведет к
{"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) используйте стратегию экспоненциальной задержки: подождите 1 с, затем 2 с, 4 с и так далее. Это предотвратит перегрузку API и гарантирует успешное выполнение запроса после снятия блокировки.
По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.