Resiliência blindada: como implementar circuit breakers e tratamento de erros com o sdk da useflagly

Protegendo sua aplicação contra falhas físicas de rede e tetos de rate limit de APIs de terceiros utilizando fallbacks robustos no backend.

Na engenharia de software moderna, falhas não são uma possibilidade — são uma certeza estatística. Em sistemas distribuídos, depender de APIs externas significa expor sua aplicação a latências imprevisíveis, cabos de rede rompidos e bloqueios por limites de taxa (rate limiting). Quando o seu microsserviço precisa tomar decisões dinâmicas, uma falha na comunicação com o motor de regras ou a ultrapassagem do teto de 300 requisições por minuto não pode resultar em uma tela de erro para o usuário final.

Arquitetando a tolerância a falhas: da estrutura organizacional ao fail-safe

Para implementar um controle de resiliência impecável, estruturamos nosso ecossistema através da hierarquia estrita da Useflagly: Scenario > Flow > FlowPart > Flag. Criamos o Scenario 'infra-resilience', o Flow 'gateway-protections' e o FlowPart 'billing-flows', que por sua vez abriga a Flag 'stripe-circuit-breaker'. Vale lembrar: Scenario, Flow e FlowPart servem estritamente para catalogação visual e organização no painel; toda a inteligência e as regras dinâmicas de negócio vivem exclusivamente nas Validations da Flag. Se o microsserviço falhar ao consultar o estado da Flag devido a problemas de rede ou cota esgotada, a aplicação captura o erro de forma determinística e aplica um fallback seguro, garantindo que o usuário continue operando sem fricção.

import { UseFlaglyClient } from '@useflagly/sdk-javascript';

// Inicialização do cliente Useflagly
const client = new UseFlaglyClient({
  token: 'uf_prd_live_9b8a7c6d5e4f3a2b'
});

async function checkPaymentGatewayWithCircuitBreaker(userId: string): Promise<boolean> {
  try {
    // Avaliação da flag enviando o contexto para validações personalizadas
    const response = await client.validateFlag('stripe-circuit-breaker', {
      identifier: userId,
      context: {
        clientPlatform: 'web'
      }
    }, 'PRD');

    if (response.statusCode === 200 && response.data['stripe-circuit-breaker']) {
      return true; // Gateway principal ativo e saudável
    }
    return false; // Desviar tráfego de forma controlada

  } catch (error: any) {
    // Tratamento de erros de alta resiliência mapeados de forma uniforme no SDK
    if (error.isNetworkError) {
      // Captura falhas físicas de rede, falhas de DNS ou timeouts (statusCode === 0)
      console.warn('[Useflagly] Falha física de rede detectada. Ativando disjuntor de emergência.');
    } else if (error.isSubscriptionError) {
      // Captura HTTP 403: Cota do plano excedida, faturamento em atraso ou assinatura suspensa
      console.warn('[Useflagly] Limite do plano atingido ou assinatura inativa. Ativando comportamento seguro.');
    } else if (error.isUnauthorized) {
      // Captura HTTP 401: Token inválido ou revogado
      console.error('[Useflagly] Credenciais de API inválidas.');
    } else {
      console.error('[Useflagly] Erro inesperado na validação:', error.message);
    }
    
    // Fallback de segurança (Fail-Safe): mantém a operação no ar usando o gateway alternativo
    return false;
  }
}

A importância de um sdk livre de estado e limites claros de rate limit

Diferente de arquiteturas complexas que exigem armazenamento local ou sincronização offline pesada, o @useflagly/sdk-javascript funciona como um cliente HTTP puro e totalmente sem estado. Toda a inteligência de processamento das Validations e o gerenciamento de cache de duas camadas (L1 em memória do servidor com TTL de 10 minutos e L2 via Redis com TTL de 2000 segundos) ocorrem de forma centralizada nos servidores da Useflagly. Isso reduz drasticamente a pegada de runtime e o bundle size no seu microsserviço. Contudo, para proteger a estabilidade global, a API impõe um limite estrito de 300 requisições por minuto por chave. Compreender e mapear esses limites através dos getters nativos como error.isNetworkError (para statusCode === 0) e error.isSubscriptionError é o que diferencia sistemas amadores de arquiteturas resilientes de nível enterprise.

⚠️ Atenção: Nunca deixe de envelopar suas chamadas de validação de flag em blocos try-catch. Sem o tratamento explícito de exceções, falhas de infraestrutura externa ou interrupções de faturamento podem propagar erros fatais e derrubar sua esteira de microsserviços.

🚩 useflagly.com.br