Exception: Mailblastr::Error

Inherits:
StandardError
  • Object
show all
Defined in:
lib/mailblastr/error.rb

Overview

Raised for every non-2xx API response. Mirrors the API error shape { statusCode, name, message }:

begin
Mailblastr::Emails.send(params)
rescue Mailblastr::Error => e
e.status_code # => 422
e.name        # => "validation_error"
e.message     # => "The `from` address must use a verified domain."
end

Match on #name, never on #message — messages are scrubbed of provider identifiers server-side and are not a stable contract. A handler may also answer with a status other than the one a name usually maps to, so read #status_code rather than assuming one from the name.

Some errors carry additive fields on top of those three. The whole parsed body is kept on #body, with the common extras surfaced as readers that return nil on an ordinary error:

rescue Mailblastr::Error => e
if (cap = e.limit)                   # WHICH quota ran out
  cap["kind"]                        # => "emails_daily"
  cap["used"]; cap["limit"]          # => 100, 100
  cap.dig("next_plan", "name")       # => "Pro"
end
e.reputation                         # reputation gates
e.sent                               # a batch that failed part way through
e.sent_count                         #   — do NOT resend these
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message = nil, status_code: nil, error_name: nil, body: nil) ⇒ Error

Returns a new instance of Error.



41
42
43
44
45
46
 
# File 'lib/mailblastr/error.rb', line 41

def initialize(message = nil, status_code: nil, error_name: nil, body: nil)
  super(message)
  @status_code = status_code
  @error_name = error_name
  @body = body.is_a?(Hash) ? body : {}
end

Instance Attribute Details

#body ⇒ Object (readonly)

The full parsed error body ({} when the response was not a JSON object). Read it for any additive field newer than this SDK version.



39
40
41
 
# File 'lib/mailblastr/error.rb', line 39

def body
  @body
end

#error_name ⇒ Object (readonly)

Returns the value of attribute error_name.



35
36
37
 
# File 'lib/mailblastr/error.rb', line 35

def error_name
  @error_name
end

#status_code ⇒ Object (readonly)

Returns the value of attribute status_code.



35
36
37
 
# File 'lib/mailblastr/error.rb', line 35

def status_code
  @status_code
end

Instance Method Details

#limit ⇒ Object

The plan/quota cap this request hit, else nil. Carried by plan_limit_reached, every *_quota_exceeded, contact_limit_reached and ai_credits_exceeded — it says WHICH quota ran out, how much of it was used, and the cheapest plan that would fit.



57
58
59
 
# File 'lib/mailblastr/error.rb', line 57

def limit
  hash_field("limit")
end

#name ⇒ Object

The API error name (e.g. "validation_error", "not_found").



49
50
51
 
# File 'lib/mailblastr/error.rb', line 49

def name
  @error_name
end

#reputation ⇒ Object

The reputation-gate detail on reputation_paused / reputation_limit_exceeded, else nil. Carries at least "retryable" and "scope" ("tenant" | "domain" | "platform").



64
65
66
 
# File 'lib/mailblastr/error.rb', line 64

def reputation
  hash_field("reputation")
end

#sent ⇒ Object

The emails that were already sent before a batch failed part way through (POST /emails/batch with an idempotency_key), else nil. Do NOT resend them.



70
71
72
73
 
# File 'lib/mailblastr/error.rb', line 70

def sent
  value = @body["sent"]
  value.is_a?(Array) ? value : nil
end

#sent_count ⇒ Object

How many emails went out before a batch failed part way through, else nil. Falls back to #sent's size when the body carried the list but not the count.



77
78
79
80
81
82
 
# File 'lib/mailblastr/error.rb', line 77

def sent_count
  count = @body["sent_count"]
  return count if count.is_a?(Integer)

  sent&.size
end