Códigos de Erro ⚠️

Entenda os erros retornados pela API

Estrutura de Erro

Quando ocorre um erro, a API retorna uma resposta no seguinte formato:

json

{
  "success": false,
  "error": "Descrição do erro",
  "message": "Informações adicionais sobre o erro"
}

Códigos de Status HTTP

2xx - Sucesso

200OK

Requisição bem-sucedida. A operação foi completada com sucesso.

json

{
  "success": true,
  "message": "Operação realizada com sucesso",
  "data": { ... }
}

201Created

Recurso criado com sucesso.

4xx - Erros do Cliente

400Bad Request

Requisição inválida ou malformada. Verifique os parâmetros enviados.

json

{
  "success": false,
  "error": "URL inválida",
  "message": "A URL fornecida não é válida ou não é suportada"
}

401Unauthorized

API Key não fornecida ou inválida.

json

{
  "success": false,
  "error": "API key não fornecida"
}

// ou

{
  "success": false,
  "error": "API key inválida"
}

402Payment Required

Créditos insuficientes para realizar a operação.

json

{
  "success": false,
  "error": "Créditos esgotados. Recarregue sua conta."
}

403Forbidden

API Key expirada ou desativada.

json

{
  "success": false,
  "error": "API key expirada"
}

// ou

{
  "success": false,
  "error": "API key desativada"
}

404Not Found

Endpoint não encontrado. Verifique a URL.

json

{
  "success": false,
  "error": "Endpoint não encontrado"
}

429Too Many Requests

Rate limit atingido. Aguarde antes de fazer novas requisições.

json

{
  "success": false,
  "error": "Limite de requisições atingido. Tente novamente mais tarde."
}

5xx - Erros do Servidor

500Internal Server Error

Erro interno do servidor. Tente novamente mais tarde.

json

{
  "success": false,
  "error": "Erro interno do servidor"
}

503Service Unavailable

Serviço temporariamente indisponível. Manutenção ou sobrecarga.

json

{
  "success": false,
  "error": "Serviço temporariamente indisponível"
}

Erros Comuns e Soluções

❌ "API key não fornecida"

Causa: Você não incluiu o header X-API-Key na requisição.

Solução:

bash

curl -X POST https://api.alauda.mz/api/... \
  -H "X-API-Key: sua_api_key_aqui" \  ← Adicione isso
  -H "Content-Type: application/json"

❌ "Créditos esgotados"

Causa: Sua conta não tem créditos suficientes.

Solução:

• Faça upgrade do seu plano
• Aguarde a renovação mensal
• Entre em contato para recarregar créditos

❌ "URL inválida"

Causa: A URL fornecida não é válida ou não é suportada.

Solução:

• Verifique se a URL está correta
• Use URLs completas (com https://)
• Certifique-se de que é uma URL suportada pela plataforma

❌ "Limite de requisições atingido"

Causa: Você atingiu o rate limit do seu plano.

Solução:

• Aguarde alguns minutos antes de tentar novamente
• Faça upgrade para um plano com rate limit maior
• Implemente retry com backoff exponencial

❌ "Falha ao processar download"

Causa: Erro ao baixar ou processar o conteúdo.

Solução:

• Verifique se o conteúdo está disponível
• Tente novamente após alguns segundos
• Verifique se não é conteúdo privado

Boas Práticas de Tratamento de Erros

Exemplo de tratamento robusto

javascript

async function downloadVideo(url) {
  try {
    const response = await fetch('https://api.alauda.mz/api/youtube/download', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ url })
    });

    const data = await response.json();

    if (!response.ok) {
      // Trata erros específicos
      switch (response.status) {
        case 401:
          throw new Error('API Key inválida ou não fornecida');
        case 402:
          throw new Error('Créditos insuficientes');
        case 429:
          throw new Error('Rate limit atingido. Aguarde e tente novamente');
        default:
          throw new Error(data.error || 'Erro desconhecido');
      }
    }

    return data.data;
  } catch (error) {
    console.error('Erro ao baixar vídeo:', error.message);
    throw error;
  }
}

💡

Dica

Sempre implemente tratamento de erros adequado em suas aplicações. Nunca assuma que uma requisição será bem-sucedida.

⚠️

Importante

Se você encontrar erros 5xx repetidamente, entre em contato com o suporte. Estes erros geralmente indicam problemas no servidor que precisam ser investigados.