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
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
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
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
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}`);
}
});
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é.
Pour toute question ou tout problème concernant l’API, contactez-nous à l’adresse api@moknah.io.