Exception: BrainzLab::Error

Inherits:
StandardError
  • Object
show all
Defined in:
lib/brainzlab/errors.rb

Overview

Base error class for all BrainzLab SDK errors. Provides structured error information including hints and documentation links.

Examples:

Raising a structured error

raise BrainzLab::Error.new(
  "Operation failed",
  hint: "Check your network connection",
  docs_url: "https://docs.brainzlab.io/troubleshooting",
  code: "operation_failed"
)

Catching and inspecting errors

begin
  BrainzLab::Vault.get("secret")
rescue BrainzLab::Error => e
  puts e.message    # What went wrong
  puts e.hint       # How to fix it
  puts e.docs_url   # Where to learn more
  puts e.code       # Machine-readable code
end

Constant Summary collapse

DOCS_BASE_URL = 
'https://docs.brainzlab.io'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil) ⇒ Error

Initialize a new BrainzLab error.

Parameters:

  • message (String) (defaults to: nil) —

    The error message describing what went wrong

  • hint (String, nil) (defaults to: nil) —

    A helpful hint on how to resolve the error

  • docs_url (String, nil) (defaults to: nil) —

    URL to relevant documentation

  • code (String, nil) (defaults to: nil) —

    Machine-readable error code

  • context (Hash, nil) (defaults to: nil) —

    Additional context about the error



47
48
49
50
51
52
53
54
 
# File 'lib/brainzlab/errors.rb', line 47

def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
  @message = message
  @hint = hint
  @docs_url = docs_url
  @code = code
  @context = context
  super(message)
end

Instance Attribute Details

#code ⇒ String? (readonly)

Returns Machine-readable error code for programmatic handling.

Returns:

  • (String, nil) —

    Machine-readable error code for programmatic handling



33
34
35
 
# File 'lib/brainzlab/errors.rb', line 33

def code
  @code
end

#context ⇒ Hash? (readonly)

Returns Additional context about the error.

Returns:

  • (Hash, nil) —

    Additional context about the error



36
37
38
 
# File 'lib/brainzlab/errors.rb', line 36

def context
  @context
end

#docs_url ⇒ String? (readonly)

Returns URL to relevant documentation.

Returns:

  • (String, nil) —

    URL to relevant documentation



30
31
32
 
# File 'lib/brainzlab/errors.rb', line 30

def docs_url
  @docs_url
end

#hint ⇒ String? (readonly)

Returns A helpful hint on how to resolve the error.

Returns:

  • (String, nil) —

    A helpful hint on how to resolve the error



27
28
29
 
# File 'lib/brainzlab/errors.rb', line 27

def hint
  @hint
end

Instance Method Details

#as_json ⇒ Object

Alias for to_h



109
110
111
 
# File 'lib/brainzlab/errors.rb', line 109

def as_json
  to_h
end

#detailed_message(highlight: false, **_kwargs) ⇒ String

Return a detailed formatted version of the error with hints and documentation links. Use this method when you want the full structured output.

Returns:

  • (String) —

    Detailed formatted error message



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/brainzlab/errors.rb', line 67

def detailed_message(highlight: false, **_kwargs)
  # Get the base message without class name duplication
  base_msg = @message || super

  parts = ["#{self.class.name}: #{base_msg}"]

  parts << "" << "Hint: #{hint}" if hint
  parts << "Docs: #{docs_url}" if docs_url
  parts << "Code: #{code}" if code

  if context && !context.empty?
    parts << "" << "Context:"
    context.each do |key, value|
      parts << "  #{key}: #{value}"
    end
  end

  parts.join("\n")
end

#inspect ⇒ String

Inspect the error for debugging

Returns:

  • (String) —

    Inspection output



90
91
92
 
# File 'lib/brainzlab/errors.rb', line 90

def inspect
  "#<#{self.class.name}: #{message}#{" (#{code})" if code}>"
end

#to_h ⇒ Hash

Return a hash representation of the error for logging/serialization.

Returns:

  • (Hash) —

    Error details as a hash



97
98
99
100
101
102
103
104
105
106
 
# File 'lib/brainzlab/errors.rb', line 97

def to_h
  {
    error_class: self.class.name,
    message: message,
    hint: hint,
    docs_url: docs_url,
    code: code,
    context: context
  }.compact
end

#to_s ⇒ String

Format the error as a detailed string with hints and documentation links.

Returns:

  • (String) —

    Formatted error message



59
60
61
 
# File 'lib/brainzlab/errors.rb', line 59

def to_s
  super
end