Moknah Documentação
Comece grátis
Referência da API

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

HTTP: 401 WSS: 4001 / 4002

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

HTTP: 402 WSS: JSON no meio da transmissão

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

HTTP: 409 / 429 WSS: 4290

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

HTTP: 400 WSS: JSON no meio da transmissão

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}`);
    }
});
Boa prática: Backoff exponencial

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.

Suporte da API

Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.