Exception: Forem::ForemError

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

Overview

Base error class for all errors raised by the forem-ruby library.

Every error exposes the raw HTTP context (status code, body, headers) so callers can inspect the upstream response without re-issuing the request.

Examples:

Rescuing a specific subclass

begin
  Forem::Article.retrieve(99999999)
rescue Forem::NotFoundError => e
  puts "#{e.http_status}: #{e.message}"
end

Rescuing any Forem error

rescue Forem::ForemError => e
  logger.error(e.message)
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil, code: nil) ⇒ ForemError

Initialize a new ForemError.

Parameters:

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

    a human-readable description of the error.

  • http_status (Integer, nil) (defaults to: nil) —

    the HTTP status code from the response.

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

    the raw HTTP response body.

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

    a hash of HTTP response headers.

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

    a machine-readable error code from the API.



43
44
45
46
47
48
49
 
# File 'lib/forem/errors.rb', line 43

def initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil, code: nil)
  @http_status = http_status
  @http_body = http_body
  @http_headers = http_headers
  @code = code
  super(message)
end

Instance Attribute Details

#code ⇒ String? (readonly)

Returns an optional machine-readable error code extracted from the API response body, or nil.

Returns:

  • (String, nil) —

    an optional machine-readable error code extracted from the API response body, or nil.



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

def code
  @code
end

#http_body ⇒ String? (readonly)

Returns the raw HTTP response body as a string, or nil.

Returns:

  • (String, nil) —

    the raw HTTP response body as a string, or nil.



26
27
28
 
# File 'lib/forem/errors.rb', line 26

def http_body
  @http_body
end

#http_headers ⇒ Hash? (readonly)

Returns a hash of HTTP response headers, or nil.

Returns:

  • (Hash, nil) —

    a hash of HTTP response headers, or nil.



29
30
31
 
# File 'lib/forem/errors.rb', line 29

def http_headers
  @http_headers
end

#http_status ⇒ Integer? (readonly)

Returns the HTTP status code returned by the server (e.g. 401, 404, 429), or nil if no HTTP response was received.

Returns:

  • (Integer, nil) —

    the HTTP status code returned by the server (e.g. 401, 404, 429), or nil if no HTTP response was received.



23
24
25
 
# File 'lib/forem/errors.rb', line 23

def http_status
  @http_status
end

Instance Method Details

#parsed_body ⇒ Hash, ...

The response body parsed as JSON.

Useful when the API returns structured detail alongside an error. An empty or unparseable body yields nil.

Examples:

Reading a field the API returned with the error

begin
  client.badge_achievements.create(user_id: 123, badge_id: 45)
rescue Forem::ConflictError => e
  e.parsed_body&.dig("achievement_id")
end

Returns:

  • (Hash, Array, nil) —

    the parsed body, or nil when there is nothing parseable to return.



65
66
67
68
69
70
71
 
# File 'lib/forem/errors.rb', line 65

def parsed_body
  return @parsed_body if defined?(@parsed_body)

  @parsed_body = (JSON.parse(http_body) if http_body && !http_body.empty?)
rescue JSON::ParserError
  @parsed_body = nil
end