Errori
Comprendere le risposte di errore dell'API, i codici di chiusura WebSocket e come gestirli
Formato di errore API REST (HTTP)
Quando si verifica un errore su un endpoint HTTP standard, l'API restituisce una risposta JSON con la seguente struttura:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descrizione dell'errore leggibile",
"details": {
// Contesto aggiuntivo (varia in base al tipo di errore)
}
}
}
Formato di errore WebSocket (WSS)
I WebSocket gestiscono gli errori in modo diverso. Gli errori possono verificarsi durante l'handshake di connessione iniziale o a metà flusso mentre viene generato l'audio.
- Errori fatali: La connessione viene interrotta con uno specifico codice di chiusura (ad es. 4290).
- Errori a metà flusso: Il server invia un frame di errore JSON piatto prima di chiudere:
{"error": "Crediti insufficienti durante il flusso"}
Codici di stato e codici di chiusura
Codici di stato HTTP (REST)
| Stato | Significato | Descrizione |
|---|---|---|
200 |
OK | Richiesta riuscita |
400 |
Richiesta non valida | Parametri della richiesta non validi o richiesta malformata |
401 |
Non autorizzato | Chiave API mancante o non valida |
402 |
Pagamento richiesto | Crediti insufficienti per completare la richiesta |
403 |
Accesso negato | La chiave API non dispone dei permessi per questa azione |
404 |
Non trovato | La risorsa richiesta non esiste |
409 |
Conflitto | La richiesta è in conflitto con lo stato attuale (ad es. richiesta HTTP simultanea) |
429 |
Troppe richieste | Limite di richieste superato |
500 |
Errore interno del server | Qualcosa è andato storto da parte nostra |
Codici di chiusura WebSocket (WSS)
| Codice | Tipo | Descrizione |
|---|---|---|
1000 |
Chiusura normale | Flusso completato con successo. |
3011 |
Errore di generazione | Generazione audio non riuscita sull'API a monte. Riprova la richiesta. |
4001 |
Autenticazione mancante | Nessuna chiave API fornita nell'intestazione Authorization durante l'handshake. |
4002 |
Autenticazione non riuscita | Chiave non valida, account inattivo, crediti iniziali insufficienti o restrizione IP. |
4290 |
Limite di simultaneità | Hai già una connessione WebSocket TTS attiva. Il limite è 1 per utente. |
Scenari di errore comuni
1. Non autorizzato / Autenticazione non riuscita
Autenticazione non riuscita a causa di una chiave API mancante o non valida, o di restrizioni della whitelist IP.
Cause comuni:
- Header Authorization: Bearer mancante
- Formato della chiave API non valido o chiave revocata
- Connessione da un indirizzo IP non presente nella whitelist della tua chiave
2. Crediti insufficienti
Il tuo account non ha crediti sufficienti per completare questa richiesta.
- HTTP: Fallisce immediatamente prima di generare l'audio.
- WebSocket: Se esaurisci i crediti a metà flusso, il server invia
{"error": "Crediti insufficienti durante il flusso"}e chiude correttamente la connessione. L'audio generato prima dell'esaurimento dei crediti verrà comunque consegnato.
3. Concorrenza e limiti di frequenza
Moknah elabora una richiesta per utente alla volta per garantire un utilizzo equo.
- HTTP 409: Un'altra richiesta dal tuo account è già in fase di elaborazione. Attendi che termini.
- HTTP 429: Hai superato il limite di 60 richieste al minuto (RPM).
- WSS 4290: Hai tentato di aprire una seconda connessione WebSocket mentre la prima era ancora attiva.
4. Richiesta non valida / Dati errati
I parametri della richiesta non sono validi o hai superato i limiti dei blocchi di testo.
- HTTP: Campi obbligatori mancanti (text, voice_id).
- WebSocket: L'invio di un blocco di testo superiore a 2.000 caratteri comporterà
{"error": "Blocco troppo grande. Massimo 2000 caratteri per blocco."}.
Gestione degli errori nel codice
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("Crediti insufficienti")
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) # Riprova
elif response.status_code == 409:
time.sleep(5)
return generate_speech(text, voice_id, api_key) # Riprova
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}`);
}
});
Per gli errori 429 (HTTP), 409 (HTTP) e 4290 (WSS), implementa il backoff esponenziale: attendi 1s, poi 2s, poi 4s, ecc. Questo evita di sovraccaricare l'API e garantisce che la richiesta vada a buon fine una volta rimosso il blocco.
Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.