Moknah Documents
Commencez gratuitement
Référence de l’API

Erreurs

Comprendre les réponses d’erreur des API, les codes de fermeture WebSocket et la manière de les gérer

Format d’erreur de l’API REST (HTTP)

Lorsqu’une erreur survient sur un point de terminaison HTTP standard, l’API renvoie une réponse JSON présentant la structure suivante :

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Description de l’erreur lisible par l’humain",
        "details": {
          // Contexte supplémentaire (varie selon le type d’erreur)
        }
    }
}

Format d’erreur WebSocket (WSS)

Les WebSockets gèrent les erreurs différemment. Des erreurs peuvent survenir lors de la phase initiale d’établissement de la connexion ou en cours de flux, pendant la génération de l’audio.

  • Erreurs fatales : La connexion est interrompue avec un code de fermeture spécifique (par exemple, 4290).
  • Erreurs en cours de traitement : Le serveur envoie une trame d’erreur JSON plate avant de fermer la connexion : {"error": "Crédits insuffisants pendant le flux"}

Codes d’état et codes de fermeture

Codes d’état HTTP (REST)

Statut Signification Description
200 D’accord La requête a réussi.
400 Requête incorrecte Paramètres de requête invalides ou requête mal formée
401 Non autorisé Clé API manquante ou invalide
402 Paiement requis Crédits insuffisants pour effectuer la demande
403 Interdit La clé API ne dispose pas de l’autorisation nécessaire pour cette action.
404 Introuvable La ressource demandée n’existe pas.
409 Conflit La requête entre en conflit avec l’état actuel (par ex. une requête HTTP concurrente).
429 Trop de requêtes Limite de débit dépassée
500 Erreur interne du serveur Un problème est survenu de notre côté.

Codes de fermeture WebSocket (WSS)

Code Type Description
1000 Fermeture normale Flux terminé avec succès.
3011 Erreur de génération La génération audio a échoué au niveau de l’API en amont. Veuillez réessayer la requête.
4001 Authentification manquante Aucune clé API n’a été fournie dans l’en-tête Authorization lors de la phase d’établissement de la connexion.
4002 Échec de l’authentification Clé invalide, compte inactif, crédits initiaux insuffisants ou restriction IP.
4290 Limite de simultanéité Vous avez déjà une connexion WebSocket TTS active. La limite est de 1 par utilisateur.

Scénarios d’erreur courants

1. Non autorisé / Échec de l’authentification

HTTP : 401 WSS : 4001 / 4002

L’authentification a échoué en raison d’une clé API manquante ou invalide, ou de restrictions liées à la liste blanche d’adresses IP.

Causes fréquentes :

  • En-tête Authorization: Bearer manquant
  • Format de clé API invalide ou clé révoquée
  • Connexion depuis une adresse IP ne figurant pas dans la liste blanche de votre clé

2. Crédits insuffisants

HTTP : 402 WSS : JSON en cours de flux

Votre compte ne dispose pas de suffisamment de crédits pour effectuer cette demande.

  • HTTP : Échoue juste avant la génération de l’audio.
  • WebSocket : Si vous êtes à court de crédits en cours de diffusion, le serveur envoie {"error": "Crédits insuffisants pendant le flux"} et ferme la connexion proprement. L’audio généré avant l’épuisement des crédits sera tout de même transmis.

3. Concurrence et limites de débit

HTTP : 409 / 429 WSS : 4290

Moknah traite une seule demande par utilisateur à la fois afin de garantir une utilisation équitable.

  • HTTP 409 : Une autre demande provenant de votre compte est déjà en cours de traitement. Attendez qu’elle soit terminée.
  • HTTP 429 : Vous avez dépassé la limite de 60 requêtes par minute (RPM).
  • WSS 4290 : Vous avez tenté d’ouvrir une seconde connexion WebSocket alors que la première était encore active.

4. Requête invalide / Données incorrectes

HTTP : 400 WSS : JSON en cours de flux

Les paramètres de la requête sont invalides ou vous avez dépassé les limites de taille des segments de texte.

  • HTTP : Champs obligatoires manquants (text, voice_id).
  • WebSocket : L’envoi d’un bloc de texte de plus de 2 000 caractères entraînera {"error": "Segment trop volumineux. Maximum de 2000 caractères par segment."}.

Gestion des erreurs dans le code

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  # Extraits audio
    elif response.status_code == 402:
        raise Exception("Crédits insuffisants")
    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)  # Réessayer
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # Réessayer
    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}`);
    }
});
Bonne pratique : backoff exponentiel

Pour les erreurs 429 (HTTP), 409 (HTTP) et 4290 (WSS), mettez en œuvre une stratégie de temporisation exponentielle (exponential backoff) : attendez 1 s, puis 2 s, puis 4 s, etc. Cela évite de surcharger l’API et garantit la réussite de votre requête une fois le verrou levé.

Support API

Pour toute question ou tout problème concernant l’API, contactez-nous à l’adresse api@moknah.io.