Exception: ApolloDeploySignalSdk::SDKError

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

Overview

Structured error raised on API and network failures.

Inherits from StandardError and provides structured access to error details including status code, error code, request ID, and convenience methods for common error classifications.

Examples:

Basic error handling

begin
  client.users.get_user(id: "123")
rescue ApolloDeploySignalSdk::SDKError => e
  puts "Error #{e.status}: #{e.message} (#{e.code})"
  puts "Request ID: #{e.request_id}" if e.request_id

  if e.rate_limited?
    sleep 1
    retry
  end

  if e.server_error?
    # Log and alert
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message, status = 0, code = "unknown_error", request_id: nil, timestamp: nil, path: nil, method: nil, hint: nil, details: nil) ⇒ SDKError

Create a new SDKError.

Parameters:

  • message (String) —

    human-readable error message

  • status (Integer) (defaults to: 0) —

    HTTP status code (0 for network errors)

  • code (String) (defaults to: "unknown_error") —

    machine-readable error code

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

    server-provided request ID

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

    error timestamp

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

    request path

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

    HTTP method

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

    resolution hint

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

    structured error details



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 62

def initialize(
  message,
  status = 0,
  code = "unknown_error",
  request_id: nil,
  timestamp: nil,
  path: nil,
  method: nil,
  hint: nil,
  details: nil
)
  super(message)

  @code = code
  @status = status
  @request_id = request_id
  @timestamp = timestamp
  @path = path
  @method = method
  @hint = hint
  @details = details
end

Instance Attribute Details

#code ⇒ String (readonly)

Returns machine-readable error code (e.g. "not_found", "rate_limit_exceeded").

Returns:

  • (String) —

    machine-readable error code (e.g. "not_found", "rate_limit_exceeded")



28
29
30
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 28

def code
  @code
end

#details ⇒ Hash? (readonly)

Returns structured error details.

Returns:

  • (Hash, nil) —

    structured error details



49
50
51
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 49

def details
  @details
end

#hint ⇒ String? (readonly)

Returns helpful hint for resolving the error.

Returns:

  • (String, nil) —

    helpful hint for resolving the error



46
47
48
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 46

def hint
  @hint
end

#method ⇒ String? (readonly)

Returns HTTP method that caused the error.

Returns:

  • (String, nil) —

    HTTP method that caused the error



43
44
45
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 43

def method
  @method
end

#path ⇒ String? (readonly)

Returns request path that caused the error.

Returns:

  • (String, nil) —

    request path that caused the error



40
41
42
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 40

def path
  @path
end

#request_id ⇒ String? (readonly)

Returns unique request identifier from the server.

Returns:

  • (String, nil) —

    unique request identifier from the server



34
35
36
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 34

def request_id
  @request_id
end

#status ⇒ Integer (readonly)

Returns HTTP status code (0 for network errors).

Returns:

  • (Integer) —

    HTTP status code (0 for network errors)



31
32
33
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 31

def status
  @status
end

#timestamp ⇒ String? (readonly)

Returns ISO 8601 timestamp of error occurrence.

Returns:

  • (String, nil) —

    ISO 8601 timestamp of error occurrence



37
38
39
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 37

def timestamp
  @timestamp
end

Instance Method Details

#auth_error? ⇒ Boolean

Returns true if the error is authentication-related.

Returns:

  • (Boolean) —

    true if the error is authentication-related



91
92
93
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 91

def auth_error?
  %w[unauthorized credential_expired credential_revoked].include?(@code)
end

#client_error? ⇒ Boolean

Returns true if status is 4xx (client error).

Returns:

  • (Boolean) —

    true if status is 4xx (client error)



117
118
119
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 117

def client_error?
  @status >= 400 && @status < 500
end

#forbidden? ⇒ Boolean

Returns true if the error is a permission error (HTTP 403).

Returns:

  • (Boolean) —

    true if the error is a permission error (HTTP 403)



96
97
98
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 96

def forbidden?
  @code == "forbidden" || @status == 403
end

#not_found? ⇒ Boolean

Returns true if the resource was not found (HTTP 404).

Returns:

  • (Boolean) —

    true if the resource was not found (HTTP 404)



101
102
103
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 101

def not_found?
  @code == "not_found" || @status == 404
end

#rate_limited? ⇒ Boolean

Returns true if the error is a rate limit (HTTP 429).

Returns:

  • (Boolean) —

    true if the error is a rate limit (HTTP 429)



86
87
88
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 86

def rate_limited?
  @code == "rate_limit_exceeded" || @status == 429
end

#retryable? ⇒ Boolean

Returns true if this error is safe to retry.

Returns:

  • (Boolean) —

    true if this error is safe to retry



122
123
124
125
126
127
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 122

def retryable?
  @code == "network_error" ||
    @code == "gateway_timeout" ||
    [408, 425, 429].include?(@status) ||
    @status >= 500
end

#server_error? ⇒ Boolean

Returns true if status is 5xx (server error).

Returns:

  • (Boolean) —

    true if status is 5xx (server error)



112
113
114
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 112

def server_error?
  @status >= 500
end

#to_h ⇒ Hash

Returns a hash representation for logging and serialization.

Returns:

  • (Hash) —

    a hash representation for logging and serialization



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 130

def to_h
  {
    name: "SDKError",
    message: message,
    status: @status,
    code: @code,
    request_id: @request_id,
    timestamp: @timestamp,
    path: @path,
    method: @method,
    hint: @hint,
    details: @details
  }.compact
end

#to_json(*args) ⇒ String

Returns JSON representation for logging.

Returns:

  • (String) —

    JSON representation for logging



146
147
148
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 146

def to_json(*args)
  to_h.to_json(*args)
end

#validation_error? ⇒ Boolean

Returns true if the error is a validation error.

Returns:

  • (Boolean) —

    true if the error is a validation error



106
107
108
109
 
# File 'lib/apollo_deploy_signal_sdk/errors.rb', line 106

def validation_error?
  %w[validation_failed request_validation_failed bad_request unprocessable_entity].include?(@code) ||
    @status == 422
end