Błędy
Zrozumienie odpowiedzi błędów API, kodów zamknięcia WebSocket oraz sposobów ich obsługi
Format błędu REST API (HTTP)
Gdy wystąpi błąd w standardowym punkcie końcowym HTTP, API zwraca odpowiedź JSON o następującej strukturze:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Czytelny dla człowieka opis błędu",
"details": {
// Dodatkowy kontekst (różni się w zależności od typu błędu)
}
}
}
Format błędu WebSocket (WSS)
WebSockety obsługują błędy w inny sposób. Błędy mogą wystąpić podczas początkowego nawiązywania połączenia (handshake) lub w trakcie transmisji podczas generowania dźwięku.
- Błędy krytyczne: Połączenie zostaje przerwane z określonym kodem zamknięcia (np. 4290).
- Błędy w trakcie transmisji: Przed zamknięciem serwer wysyła prostą ramkę błędu JSON:
{"error": "Niewystarczająca liczba kredytów podczas transmisji"}
Kody stanu i kody zamknięcia
Kody stanu HTTP (REST)
| Status | Znaczenie | Opis |
|---|---|---|
200 |
OK | Żądanie powiodło się |
400 |
Nieprawidłowe żądanie | Nieprawidłowe parametry żądania lub błędnie sformułowane żądanie |
401 |
Brak autoryzacji | Brakujący lub nieprawidłowy klucz API |
402 |
Wymagana płatność | Niewystarczająca liczba kredytów do zrealizowania żądania |
403 |
Zabronione | Klucz API nie ma uprawnień do wykonania tej czynności |
404 |
Nie znaleziono | Żądany zasób nie istnieje |
409 |
Konflikt | Żądanie koliduje z bieżącym stanem (np. jednoczesne żądanie HTTP) |
429 |
Zbyt wiele żądań | Przekroczono limit zapytań |
500 |
Wewnętrzny błąd serwera | Coś poszło nie tak po naszej stronie |
Kody zamknięcia WebSocket (WSS)
| Kod | Typ | Opis |
|---|---|---|
1000 |
Normalne zamknięcie | Transmisja zakończona pomyślnie. |
3011 |
Błąd generowania | Generowanie dźwięku w nadrzędnym API nie powiodło się. Ponów żądanie. |
4001 |
Brak uwierzytelnienia | Podczas nawiązywania połączenia (handshake) nie podano klucza API w nagłówku Authorization. |
4002 |
Błąd uwierzytelniania | Nieprawidłowy klucz, nieaktywne konto, niewystarczająca początkowa liczba kredytów lub ograniczenie IP. |
4290 |
Limit jednoczesnych połączeń | Masz już aktywne połączenie WebSocket TTS. Limit wynosi 1 na użytkownika. |
Typowe scenariusze błędów
1. Brak autoryzacji / Błąd uwierzytelniania
Uwierzytelnianie nie powiodło się z powodu brakującego lub nieprawidłowego klucza API albo ograniczeń białej listy adresów IP.
Częste przyczyny:
- Brak nagłówka Authorization: Bearer
- Nieprawidłowy format klucza API lub klucz został unieważniony
- Połączenie z adresu IP spoza białej listy przypisanej do klucza
2. Niewystarczająca liczba kredytów
Na Twoim koncie nie ma wystarczającej liczby kredytów, aby zrealizować to żądanie.
- HTTP: Kończy się niepowodzeniem tuż przed wygenerowaniem dźwięku.
- WebSocket: Jeśli kredyty wyczerpią się w trakcie strumieniowania, serwer wysyła
{"error": "Niewystarczająca liczba kredytów podczas transmisji"}i prawidłowo zamyka połączenie. Dźwięk wygenerowany przed wyczerpaniem kredytów zostanie mimo to dostarczony.
3. Współbieżność i limity zapytań
Moknah przetwarza jedno żądanie na użytkownika naraz, aby zapewnić uczciwe korzystanie z usługi.
- HTTP 409: Inne żądanie z Twojego konta jest już przetwarzane. Poczekaj na jego zakończenie.
- HTTP 429: Przekroczono limit 60 żądań na minutę (RPM).
- WSS 4290: Podjęto próbę otwarcia drugiego połączenia WebSocket, gdy pierwsze było nadal aktywne.
4. Nieprawidłowe żądanie / Błędne dane
Parametry żądania są nieprawidłowe lub przekroczono limit długości fragmentu tekstu.
- HTTP: Brak wymaganych pól (text, voice_id).
- WebSocket: Wysłanie fragmentu tekstu dłuższego niż 2000 znaków spowoduje błąd
{"error": "Fragment jest za duży. Maksymalnie 2000 znaków na fragment."}.
Obsługa błędów w kodzie
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 # Bajty audio
elif response.status_code == 402:
raise Exception("Niewystarczająca liczba kredytów")
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) # Ponów
elif response.status_code == 409:
time.sleep(5)
return generate_speech(text, voice_id, api_key) # Ponów
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}`);
}
});
W przypadku błędów 429 (HTTP), 409 (HTTP) i 4290 (WSS) zastosuj wykładniczy czas odczekania (exponential backoff): odczekaj 1 s, następnie 2 s, 4 s itd. Zapobiega to przeciążeniu API i gwarantuje, że żądanie powiedzie się po zwolnieniu blokady.
W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.