Moknah Documenti
Inizia gratis
Riferimento API

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

HTTP: 401 WSS: 4001 / 4002

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

HTTP: 402 WSS: JSON a metà flusso

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

HTTP: 409 / 429 WSS: 4290

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

HTTP: 400 WSS: JSON a metà flusso

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}`);
    }
});
Best practice: backoff esponenziale

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.

Supporto API

Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.