Erros
Entenda as respostas de erro da API, os códigos de fechamento WebSocket e como lidar com eles
Formato de erro da API REST (HTTP)
Quando ocorre um erro em um endpoint HTTP padrão, a API retorna uma resposta JSON com a seguinte estrutura:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descrição do erro legível para humanos",
"details": {
// Contexto adicional (varia conforme o tipo de erro)
}
}
}
Formato de erro do WebSocket (WSS)
Os WebSockets lidam com erros de forma diferente. Os erros podem ocorrer durante o handshake da conexão inicial ou no meio da transmissão enquanto o áudio está sendo gerado.
- Erros fatais: A conexão é encerrada com um código de fechamento específico (ex.: 4290).
- Erros durante a transmissão: O servidor envia um quadro de erro JSON simples antes de fechar:
{"error": "Créditos insuficientes durante a transmissão"}
Códigos de status e códigos de fechamento
Códigos de status HTTP (REST)
| Status | Significado | Descrição |
|---|---|---|
200 |
OK | Solicitação bem-sucedida |
400 |
Solicitação inválida | Parâmetros de solicitação inválidos ou solicitação malformada |
401 |
Não autorizado | Chave de API ausente ou inválida |
402 |
Pagamento necessário | Créditos insuficientes para concluir a solicitação |
403 |
Proibido | A chave de API não tem permissão para esta ação |
404 |
Não encontrado | O recurso solicitado não existe |
409 |
Conflito | A solicitação entra em conflito com o estado atual (ex.: solicitação HTTP simultânea) |
429 |
Muitas solicitações | Limite de requisições excedido |
500 |
Erro interno do servidor | Algo deu errado do nosso lado |
Códigos de fechamento do WebSocket (WSS)
| Código | Tipo | Descrição |
|---|---|---|
1000 |
Fechamento normal | Transmissão concluída com sucesso. |
3011 |
Erro de geração | A geração de áudio falhou na API de origem. Tente novamente. |
4001 |
Autenticação ausente | Nenhuma chave de API fornecida no cabeçalho Authorization durante o handshake. |
4002 |
Falha na autenticação | Chave inválida, conta inativa, créditos iniciais insuficientes ou restrição de IP. |
4290 |
Limite de simultaneidade | Você já tem uma conexão WebSocket de TTS ativa. O limite é de 1 por usuário. |
Cenários comuns de erro
1. Não autorizado / Falha na autenticação
Falha na autenticação devido a uma chave de API ausente ou inválida, ou restrições da lista de permissões de IP.
Causas comuns:
- Cabeçalho Authorization: Bearer ausente
- Formato de chave de API inválido ou a chave foi revogada
- Conexão a partir de um endereço IP que não está na lista de permissões da sua chave
2. Créditos insuficientes
Sua conta não tem créditos suficientes para concluir esta solicitação.
- HTTP: Falha imediatamente antes de gerar o áudio.
- WebSocket: Se seus créditos acabarem no meio da transmissão, o servidor envia
{"error": "Créditos insuficientes durante a transmissão"}e encerra a conexão corretamente. O áudio gerado antes do término dos créditos ainda será entregue.
3. Simultaneidade e limites de taxa
A Moknah processa uma solicitação por usuário de cada vez para garantir o uso justo.
- HTTP 409: Outra solicitação da sua conta já está sendo processada. Aguarde até que ela termine.
- HTTP 429: Você excedeu o limite de 60 solicitações por minuto (RPM).
- WSS 4290: Você tentou abrir uma segunda conexão WebSocket enquanto a primeira ainda estava ativa.
4. Solicitação inválida / Dados incorretos
Os parâmetros da solicitação são inválidos ou você excedeu os limites de blocos de texto.
- HTTP: Campos obrigatórios ausentes (text, voice_id).
- WebSocket: Enviar um bloco de texto maior que 2.000 caracteres resultará em
{"error": "Bloco muito grande. Máximo de 2000 caracteres por bloco."}.
Tratamento de erros no código
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 # Bytes de áudio
elif response.status_code == 402:
raise Exception("Créditos insuficientes")
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) # Tentar novamente
elif response.status_code == 409:
time.sleep(5)
return generate_speech(text, voice_id, api_key) # Tentar novamente
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}`);
}
});
Para erros 429 (HTTP), 409 (HTTP) e 4290 (WSS), implemente o backoff exponencial: aguarde 1s, depois 2s, depois 4s, etc. Isso evita sobrecarregar a API e garante que sua solicitação será bem-sucedida assim que o bloqueio for liberado.
Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.