Tratamento de Erros

A API External do Efflux usa códigos de status HTTP padrão e retorna respostas de erro estruturadas para ajudar você a identificar e resolver problemas.

Formato de Resposta de Erro

Todas as respostas de erro seguem uma estrutura JSON consistente:

{
  "error": "Mensagem de erro legível",
  "code": "CODIGO_ERRO"
}

Campo	Tipo	Descrição
error	string	Uma descrição legível do erro
code	string	Um código de erro legível por máquina para tratamento programático

Códigos de Status HTTP

Status	Categoria	Descrição
400	Bad Request	Parâmetros ou formato de requisição inválidos
401	Unauthorized	Autenticação falhou
403	Forbidden	Autenticado mas sem permissão
404	Not Found	Recurso não existe
500	Server Error	Erro interno do servidor

Erros de Autenticação (401)

Esses erros ocorrem quando a API key está ausente, inválida ou não está mais ativa.

Código	Mensagem	Causa	Resolução
MISSING_API_KEY	API key required	Header X-API-Key não fornecido	Adicione o header à sua requisição
MISSING_KEY	API key is required	API key vazia ou em branco	Forneça uma API key válida
INVALID_FORMAT	Invalid API key format	Key não corresponde ao formato esperado	Use uma key começando com efflux_live_
INVALID_KEY	Invalid API key	Key não encontrada no banco de dados	Verifique a key ou crie uma nova
KEY_EXPIRED	API key has expired	Key passou da data de expiração	Crie uma nova API key
KEY_REVOKED	API key has been revoked	Key foi revogada manualmente	Crie uma nova API key

Exemplo: Tratando Erros de Autenticação

JavaScript

async function fetchContent() {
  const response = await fetch('https://api.efflux.media/api/external/content', {
    headers: { 'X-API-Key': process.env.EFFLUX_API_KEY }
  });

  if (response.status === 401) {
    const error = await response.json();

    switch (error.code) {
      case 'KEY_EXPIRED':
      case 'KEY_REVOKED':
        // Notificar admin para criar nova key
        console.error('API key não é mais válida. Por favor, crie uma nova.');
        break;
      case 'INVALID_KEY':
      case 'INVALID_FORMAT':
        console.error('API key inválida. Verifique sua configuração.');
        break;
      case 'MISSING_API_KEY':
        console.error('API key está ausente na requisição.');
        break;
      default:
        console.error('Autenticação falhou:', error.error);
    }
    return null;
  }

  return response.json();
}

Python

import requests
import os

def fetch_content():
    response = requests.get(
        'https://api.efflux.media/api/external/content',
        headers={'X-API-Key': os.environ.get('EFFLUX_API_KEY')}
    )

    if response.status_code == 401:
        error = response.json()
        code = error.get('code')

        if code in ('KEY_EXPIRED', 'KEY_REVOKED'):
            print('API key não é mais válida. Por favor, crie uma nova.')
        elif code in ('INVALID_KEY', 'INVALID_FORMAT'):
            print('API key inválida. Verifique sua configuração.')
        elif code == 'MISSING_API_KEY':
            print('API key está ausente na requisição.')
        else:
            print(f'Autenticação falhou: {error.get("error")}')
        return None

    return response.json()

Erros de Autorização (403)

Esses erros ocorrem quando a autenticação é bem-sucedida mas a API key não possui o escopo necessário.

Código	Mensagem	Causa	Resolução
-	Missing required scope: {scope}	API key não tem o escopo necessário	Crie uma nova key com o escopo necessário

Dica

Se você receber um erro 403, verifique qual escopo o endpoint requer na Referência da API e confirme os escopos da sua API key no Backoffice.

Escopos Necessários por Endpoint

Endpoint	Escopo Necessário
/content, /content/{id}	content:read
/schedules	schedules:read
/players	players:read
/analytics/summary	analytics:read

Erros de Requisição Inválida (400)

Esses erros indicam parâmetros de requisição inválidos.

Mensagem	Causa	Resolução
Invalid status: {value}	Valor de filtro de status inválido	Use active, inactive ou archived
Invalid UUID format	UUID malformado no path	Forneça um UUID válido

Exemplo: Tratando Erros de Validação

const response = await fetch(
  'https://api.efflux.media/api/external/content?status=invalido'
);

if (response.status === 400) {
  const error = await response.json();
  console.error('Requisição inválida:', error.error);
  // error.error: "Invalid status: invalido"
}

Erros de Não Encontrado (404)

Esses erros indicam que o recurso solicitado não existe ou não pertence ao seu tenant.

Endpoint	Causa
/content/{id}	ID de conteúdo não existe ou pertence a outro tenant

Nota

Por razões de segurança, a API retorna a mesma resposta 404 seja o recurso inexistente ou pertencente a outro tenant. Isso previne ataques de enumeração.

Erros de Servidor (500)

Erros de servidor indicam um problema do lado do Efflux. São raros mas devem ser tratados graciosamente.

Boas Práticas para Erros de Servidor

1. Tente novamente com backoff exponencial
2. Registre o erro para debugging
3. Mostre mensagem amigável ao usuário
4. Contate o suporte se persistir

async function fetchWithRetry(url, options, maxRetries = 3) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status >= 500) {
        throw new Error(`Erro de servidor: ${response.status}`);
      }

      return response;
    } catch (error) {
      lastError = error;
      // Backoff exponencial: 1s, 2s, 4s
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}

Boas Práticas de Tratamento de Erros

1. Sempre Verifique Códigos de Status

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  throw new ApiError(response.status, error.code, error.error);
}

2. Crie uma Classe de Erro Customizada

class EffluxApiError extends Error {
  constructor(status, code, message) {
    super(message);
    this.status = status;
    this.code = code;
    this.name = 'EffluxApiError';
  }

  isAuthError() {
    return this.status === 401;
  }

  isScopeError() {
    return this.status === 403;
  }

  isNotFound() {
    return this.status === 404;
  }
}

3. Centralize o Tratamento de Erros

async function effluxRequest(endpoint, options = {}) {
  const response = await fetch(
    `https://api.efflux.media/api/external${endpoint}`,
    {
      ...options,
      headers: {
        'X-API-Key': process.env.EFFLUX_API_KEY,
        ...options.headers
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new EffluxApiError(response.status, error.code, error.error);
  }

  return response.json();
}

// Uso
try {
  const content = await effluxRequest('/content');
} catch (error) {
  if (error.isAuthError()) {
    handleAuthFailure(error);
  } else if (error.isNotFound()) {
    handleNotFound(error);
  } else {
    handleGenericError(error);
  }
}

4. Registre Erros para Debugging

Inclua contexto relevante ao registrar erros:

function logApiError(error, context) {
  console.error({
    timestamp: new Date().toISOString(),
    status: error.status,
    code: error.code,
    message: error.message,
    endpoint: context.endpoint,
    requestId: context.requestId
  });
}