Como Lidar com Erros Comuns ao Consumir APIs de CPF em Ruby

module CpfHub
    class Error < StandardError; end

    class ApiError < Error
    attr_reader :status_code, :response_body

    def initialize(message, status_code: nil, response_body: nil)
    @status_code = status_code
    @response_body = response_body
    super(message)
    end
    end

    class CpfInvalidoError < ApiError; end
    class AuthenticationError < ApiError; end
    class RateLimitError < ApiError
    attr_reader :retry_after

    def initialize(message, retry_after: 60, **kwargs)
    @retry_after = retry_after
    super(message, **kwargs)
    end
    end

    class CpfNaoEncontradoError < ApiError; end
    class ServerError < ApiError; end
    class TimeoutError < Error; end
    class NetworkError < Error; end
end

require "faraday"
require "json"

module CpfHub
    class Client
    BASE_URL = "https://api.cpfhub.io"

    def initialize(api_key: ENV["CPFHUB_API_KEY"])
    @api_key = api_key
    @connection = build_connection
    end

    def consultar(cpf)
    cpf_limpo = cpf.to_s.gsub(/\D/, "")
    validar_formato_cpf!(cpf_limpo)

    resposta = @connection.get("/cpf/#{cpf_limpo}")
    tratar_resposta(resposta, cpf_limpo)
    rescue Faraday::TimeoutError => e
    raise CpfHub::TimeoutError,
    "Timeout ao consultar CPF: #{e.message}"
    rescue Faraday::ConnectionFailed => e
    raise CpfHub::NetworkError,
    "Falha de conexao: #{e.message}"
    end

    private

    def build_connection
    Faraday.new(url: BASE_URL) do |conn|
    conn.headers["x-api-key"] = @api_key
    conn.headers["Content-Type"] = "application/json"
    conn.options.timeout = 10
    conn.options.open_timeout = 5
    conn.adapter Faraday.default_adapter
    end
    end

    def validar_formato_cpf!(cpf)
    unless cpf.match?(/\A\d{11}\z/)
    raise CpfHub::CpfInvalidoError.new(
    "CPF deve conter exatamente 11 digitos",
    status_code: 400
    )
    end
    end

    def tratar_resposta(resposta, cpf)
    case resposta.status
    when 200
    body = JSON.parse(resposta.body)
    return body["data"] if body["success"]

    raise CpfHub::CpfNaoEncontradoError.new(
    "CPF #{cpf} nao encontrado",
    status_code: 200,
    response_body: resposta.body
    )
    when 401
    raise CpfHub::AuthenticationError.new(
    "API key invalida ou ausente",
    status_code: 401
    )
    when 429
    retry_after = resposta.headers["Retry-After"]&.to_i || 60
    raise CpfHub::RateLimitError.new(
    "Rate limit excedido",
    status_code: 429,
    retry_after: retry_after
    )
    when 500..599
    raise CpfHub::ServerError.new(
    "Erro interno da API (#{resposta.status})",
    status_code: resposta.status,
    response_body: resposta.body
    )
    else
    raise CpfHub::ApiError.new(
    "Resposta inesperada (#{resposta.status})",
    status_code: resposta.status,
    response_body: resposta.body
    )
    end
    end
    end
end

module CpfHub
    class ResilientClient
    MAX_RETRIES = 3

    def initialize
    @client = Client.new
    end

    def consultar(cpf)
    tentativa = 0

    begin
    tentativa += 1
    @client.consultar(cpf)
    rescue CpfHub::RateLimitError => e
    if tentativa <= MAX_RETRIES
    delay = e.retry_after || (2**tentativa)
    log_retry(cpf, tentativa, delay, e)
    sleep(delay)
    retry
    end
    raise
    rescue CpfHub::ServerError, CpfHub::TimeoutError,
    CpfHub::NetworkError => e
    if tentativa <= MAX_RETRIES
    delay = (2**tentativa) + rand(0.0..1.0)
    log_retry(cpf, tentativa, delay, e)
    sleep(delay)
    retry
    end
    raise
    rescue CpfHub::CpfInvalidoError,
    CpfHub::AuthenticationError,
    CpfHub::CpfNaoEncontradoError
    raise # Não retentar erros de cliente
    end
    end

    private

    def log_retry(cpf, tentativa, delay, erro)
    puts "[CpfHub] Tentativa #{tentativa}/#{MAX_RETRIES} " \
    "para CPF #{cpf}. Retentando em #{delay.round(1)}s. " \
    "Erro: #{erro.class} - #{erro.message}"
    end
    end
end

cliente = CpfHub::ResilientClient.new

begin
    dados = cliente.consultar("12345678901")
    puts "Nome: #{dados['name']}"
    puts "Data de nascimento: #{dados['birthDate']}"
rescue CpfHub::CpfInvalidoError => e
    puts "CPF em formato invalido: #{e.message}"
rescue CpfHub::CpfNaoEncontradoError => e
    puts "CPF nao encontrado na base de dados"
rescue CpfHub::AuthenticationError => e
    puts "Erro de autenticacao. Verifique a API key."
    # Notificar equipe de operações
rescue CpfHub::RateLimitError => e
    puts "Limite de requisicoes excedido. Tente novamente em #{e.retry_after}s"
rescue CpfHub::ServerError => e
    puts "API temporariamente indisponivel (#{e.status_code})"
    # Registrar para monitoramento
rescue CpfHub::TimeoutError => e
    puts "Timeout na consulta. Verifique a conectividade."
rescue CpfHub::NetworkError => e
    puts "Erro de rede: #{e.message}"
end