mixin_bot 2.2.2 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a607209836b8c47fbcff727229f7ab93940f9b1dc5a99d4ab307345ffa952a0
-  data.tar.gz: aae920ac21d384f0a978b7e4a07e20df5c55cc6016cd7fbce1fa5231c638b742
+  metadata.gz: 419e39522e8235c79d12c0506cb4529d34ed130170acc3805fd5827eb63e7428
+  data.tar.gz: f47598cf481cd07be7ca023c329018320a63b0b111a5ba4c68b646c8bfa2819d
 SHA512:
-  metadata.gz: 46937ef32ab9ada8e3218c682fbe36a4086f7688ed5cf21ed5ad5aab575f9e8d8fe65c45220748021194500b486a538a06ddaa4d653af6762d65744c0bff51f8
-  data.tar.gz: 4a6d552a0fc8476105cf553b79ab1f2c231db95acc4cedec9131cc805758c1a68fd9845bc819f5396a42c297b3caf20f119a57e9cd066ab37d7f1cb7de04edb5
+  metadata.gz: 20330faef09d018e2c1e914a3766270648c681d79d633fefd633b6880ff40542f9b730df77ff267974507d25ebdc107bfd5005cacc15f5f0c3968c3cd4cf824f
+  data.tar.gz: db4cfbd8fd5520d076927326316ebf07682c7065597478d8892e8f94c8a13f72a17d6e3f603f1770f6a66a61fb2c1cf17562060f6c4b9f596c0b67de1baa5031

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-05-27
+
+### Added
+
+- **`MixinBot::APIError`** — structured base for API failures with `code`, `description`, `request_id`, `extra`, and helpers `retryable?`, `throttle?`, `client_error?`.
+- **Typed API errors** — `RateLimitError`, `ValidationError`, `ConflictError`, `TransferError`, `TransientError`, `AppUpdateRequiredError`, `InvalidAddressFormatError`, `ServerError`.
+- **`MixinBot.retryable?(error)`** — canonical retry policy for network timeouts, server errors (500+), and transient codes (10104, 10105).
+- **CLI** — structured error kind `rate_limit`; API errors in JSON output include `code`, `request_id`, and `throttle` when available.
+- **`test/mixin_bot/client/test_error_mapper.rb`** — unit tests for full official error-code catalog, legacy codes, HTTP fallbacks, and retry/throttle semantics.
+
+### Changed
+
+- **BREAKING: Error code mapping** — aligned to [Mixin API error codes](https://developers.mixin.one/docs/api/error-codes). Code `429` raises `RateLimitError` (not `ForbiddenError`). Codes `10002` and `20116` raise `ValidationError` and `ConflictError` respectively. `ForbiddenError` is reserved for code `403`.
+- **`Monitor.check_retryable_error`** — delegates to `MixinBot.retryable?` (no longer retries on `"insufficient"` message substrings).
+- **`Client#parse_response!`** — HTTP status fallback for 401/403/429/5xx when JSON `error` is absent (CDN/proxy edge cases).
+
+### Migration
+
+- Rescue rate limits explicitly: `rescue MixinBot::RateLimitError` (or check `error.throttle?`).
+- Replace string-based retry heuristics with `MixinBot.retryable?(error)`.
+- If you rescued `ForbiddenError` expecting throttling, update to handle `RateLimitError` separately.
+
 ## [2.2.2] - 2026-05-24
 
 ### Fixed

data/README.md

@@ -194,7 +194,11 @@ Top-level helpers on **`MixinBot::API`**: `access_token`, `encode_raw_transactio
 
 ### Errors
 
-Custom errors under `MixinBot::` include `ResponseError`, `UnauthorizedError`, `InsufficientBalanceError`, `UtxoInsufficientError`, `PinError`, and `InvalidInvoiceFormatError`. See `lib/mixin_bot/errors.rb`.
+API failures raise structured `MixinBot::APIError` subclasses with `code`, `description`, `request_id`, and behavior helpers (`retryable?`, `throttle?`). The full mapping follows the [Mixin error codes](https://developers.mixin.one/docs/api/error-codes) table — notably `429` → `RateLimitError`, not `ForbiddenError`.
+
+Use `MixinBot.retryable?(error)` for job retry decisions; use `error.throttle?` on `RateLimitError` for global backoff. `Monitor.check_retryable_error` delegates to the same policy.
+
+Local validation errors (`ArgumentError`, `InvalidInvoiceFormatError`, …) and `InsufficientAppBillingError` (billing preflight) are separate from API envelope errors. See `lib/mixin_bot/errors.rb`.
 
 ### Multiple bots
 

data/docs/agent/cli.md

@@ -72,7 +72,24 @@ Error (stderr, exit 1):
 }
 ```
 
-Error kinds: `invalid_args`, `auth`, `not_found`, `api_error`, `billing`, `unsupported`, `conflict`, `internal`.
+API failures may also include `code`, `request_id`, and `throttle` (true for rate limits):
+
+```json
+{
+  "status": "error",
+  "error": {
+    "kind": "rate_limit",
+    "message": "GET | /me | {}, errcode: 429, ...",
+    "code": 429,
+    "request_id": "abc-123",
+    "throttle": true
+  }
+}
+```
+
+Error kinds: `invalid_args`, `auth`, `not_found`, `rate_limit`, `api_error`, `billing`, `unsupported`, `conflict`, `internal`.
+
+For retry logic in automation, prefer `MixinBot.retryable?(exception)` in Ruby; CLI kinds mark `rate_limit` as non-retryable (use global backoff when `throttle` is true).
 
 ## Commands
 

data/lib/mixin_bot/cli/errors.rb

@@ -9,6 +9,7 @@ module MixinBot
       invalid_args: { retryable: false, description: 'Invalid or missing arguments' },
       auth: { retryable: false, description: 'Authentication or authorization failed' },
       not_found: { retryable: false, description: 'Requested resource was not found' },
+      rate_limit: { retryable: false, description: 'API rate limit exceeded; slow down globally' },
       api_error: { retryable: false, description: 'Mixin API returned an error' },
       unsupported: { retryable: false, description: 'Operation is not supported in this context' },
       conflict: { retryable: false, description: 'Resource exists with incompatible configuration' },
@@ -30,16 +31,19 @@ module MixinBot
 
     def kind_for_exception(error)
       case error
-      when MixinBot::ArgumentError, ::ArgumentError
+      when MixinBot::ArgumentError, ::ArgumentError, ValidationError, InvalidAddressFormatError
         :invalid_args
+      when RateLimitError
+        :rate_limit
       when UnauthorizedError, ForbiddenError, PinError, ConfigurationNotValidError
         :auth
       when NotFoundError, UserNotFoundError
         :not_found
       when InsufficientAppBillingError
         :billing
-      when ResponseError, RequestError, HttpError,
-           InsufficientBalanceError, UtxoInsufficientError, InsufficientPoolError
+      when ResponseError, RequestError, HttpError, ServerError,
+           InsufficientBalanceError, UtxoInsufficientError, InsufficientPoolError,
+           ConflictError, TransferError, TransientError, AppUpdateRequiredError
         :api_error
       else
         :internal
@@ -50,6 +54,7 @@ module MixinBot
       msg = message.to_s.downcase
       return :auth if msg.include?('unauthorized') || msg.include?('authentication')
       return :not_found if msg.include?('not found') || msg.include?('404')
+      return :rate_limit if msg.include?('too many requests') || msg.include?('errcode: 429')
       return :unsupported if msg.include?('unsupported') || msg.include?('not supported')
       return :invalid_args if msg.include?('invalid') || msg.include?('unknown')
 

data/lib/mixin_bot/cli/output.rb

@@ -84,6 +84,11 @@ module MixinBot
           }
         }
         error_body['error']['hint'] = hint if hint.present?
+        if exception.is_a?(MixinBot::APIError)
+          error_body['error']['code'] = exception.code unless exception.code.nil?
+          error_body['error']['request_id'] = exception.request_id if exception.request_id.present?
+          error_body['error']['throttle'] = true if exception.respond_to?(:throttle?) && exception.throttle?
+        end
         warn(JSON.generate(error_body))
       else
         warn(format_error(message))

data/lib/mixin_bot/client/error_mapper.rb

@@ -6,34 +6,54 @@ module MixinBot
     # Maps Mixin API +error+ objects to Ruby exceptions.
     #
     module ErrorMapper
+      CODE_MAP = {
+        400 => ValidationError,
+        401 => UnauthorizedError,
+        403 => ForbiddenError,
+        404 => NotFoundError,
+        429 => RateLimitError,
+        10_002 => ValidationError,
+        10_006 => AppUpdateRequiredError,
+        10_104 => TransientError,
+        10_105 => TransientError,
+        10_404 => UserNotFoundError,
+        20_116 => ConflictError,
+        20_117 => InsufficientBalanceError,
+        20_118 => PinError,
+        20_119 => PinError,
+        20_120 => TransferError,
+        20_121 => UnauthorizedError,
+        20_123 => ConflictError,
+        20_124 => InsufficientBalanceError,
+        20_125 => ConflictError,
+        20_127 => TransferError,
+        20_131 => ValidationError,
+        20_133 => ConflictError,
+        20_134 => TransferError,
+        20_135 => TransferError,
+        20_150 => ValidationError,
+        30_102 => InvalidAddressFormatError,
+        30_103 => InsufficientPoolError,
+        500 => ServerError,
+        7000 => ServerError,
+        7001 => ServerError
+      }.freeze
+
       module_function
 
       def raise_for!(verb:, path:, body:, response:, result:)
         err = result['error'] || {}
-        code = err['code']
-        desc = err['description']
-        req_id = response&.headers&.[]('X-Request-Id')
-        srv_time = response&.headers&.[]('X-Server-Time')
-        errmsg = "#{verb.upcase} | #{path} | #{body}, errcode: #{code}, errmsg: #{desc}, request_id: #{req_id}, server_time: #{srv_time}"
+        code = err['code']&.to_i
+        klass = CODE_MAP[code] || default_class_for_code(code)
+        raise APIError.build(klass, verb:, path:, body:, response:, result:)
+      end
+
+      def build(klass, verb:, path:, body:, response:, result:, **)
+        APIError.build(klass, verb:, path:, body:, response:, result:, **)
+      end
 
-        case code
-        when 401, 20_121
-          raise UnauthorizedError, errmsg
-        when 403, 20_116, 10_002, 429
-          raise ForbiddenError, errmsg
-        when 404
-          raise NotFoundError, errmsg
-        when 20_117
-          raise InsufficientBalanceError, errmsg
-        when 20_118, 20_119
-          raise PinError, errmsg
-        when 30_103
-          raise InsufficientPoolError, errmsg
-        when 10_404
-          raise UserNotFoundError, errmsg
-        else
-          raise ResponseError, errmsg
-        end
+      def default_class_for_code(_code)
+        ResponseError
       end
     end
   end

data/lib/mixin_bot/client.rb

@@ -125,9 +125,30 @@ module MixinBot
 
     def parse_response!(verb:, path:, body:, response:)
       result = response.body
-      return MixinBot::Models::ApiEnvelope.new(result) if result['error'].blank?
+      result = {} unless result.is_a?(Hash)
+
+      if result['error'].blank?
+        raise_http_status_error!(verb:, path:, body:, response:) if http_error_status?(response.status)
+        return MixinBot::Models::ApiEnvelope.new(result)
+      end
 
       ErrorMapper.raise_for!(verb:, path:, body:, response:, result:)
     end
+
+    def http_error_status?(status)
+      [401, 403, 429].include?(status) || status >= 500
+    end
+
+    def raise_http_status_error!(verb:, path:, body:, response:)
+      klass =
+        case response.status
+        when 429 then RateLimitError
+        when 401 then UnauthorizedError
+        when 403 then ForbiddenError
+        else ServerError
+        end
+
+      raise ErrorMapper.build(klass, verb:, path:, body:, response:, result: {})
+    end
   end
 end

data/lib/mixin_bot/errors.rb

@@ -7,7 +7,7 @@ module MixinBot
   class Error < StandardError; end
 
   ##
-  # Raised when invalid arguments are provided.
+  # Raised when invalid arguments are provided (local validation, not API code 400).
   #
   class ArgumentError < StandardError; end
 
@@ -22,34 +22,196 @@ module MixinBot
   class RequestError < Error; end
 
   ##
-  # Raised when Mixin API returns an error response.
+  # Base class for Mixin API error responses with structured metadata.
   #
-  class ResponseError < Error; end
+  class APIError < Error
+    attr_reader :code, :description, :status, :http_status, :request_id, :server_time,
+                :retry_after, :extra, :path, :verb, :body
+
+    # rubocop:disable Metrics/ParameterLists -- structured API error metadata
+    def initialize(message = nil, code: nil, description: nil, status: nil, http_status: nil,
+                   request_id: nil, server_time: nil, retry_after: nil, extra: nil,
+                   path: nil, verb: nil, body: nil)
+      @code = code&.to_i
+      @description = description
+      @status = status&.to_i
+      @http_status = http_status&.to_i
+      @request_id = request_id
+      @server_time = server_time
+      @retry_after = retry_after
+      @extra = extra
+      @path = path
+      @verb = verb
+      @body = body
+      super(message || formatted_message)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def client_error?
+      c = code.to_i
+      return true if c.between?(400, 499)
+      return true if http_status == 202 && c.positive? && c < 500
+
+      false
+    end
+
+    def retryable?
+      false
+    end
+
+    def throttle?
+      false
+    end
+
+    def formatted_message
+      format(
+        '%<verb>s | %<path>s | %<body>s, errcode: %<code>s, errmsg: %<description>s, ' \
+        'request_id: %<request_id>s, server_time: %<server_time>s',
+        verb: verb.to_s.upcase,
+        path: path.to_s,
+        body: body.to_s,
+        code: code,
+        description: description,
+        request_id: request_id,
+        server_time: server_time
+      )
+    end
+
+    class << self
+      def build(klass, verb:, path:, body:, response:, result:, code: nil, description: nil)
+        err = result.is_a?(Hash) ? (result['error'] || {}) : {}
+        resolved_code = code || err['code'] || infer_code_from_http(response)
+        resolved_description = description || err['description'] || http_status_description(response&.status)
+        headers = response&.headers || {}
+        retry_after = headers['Retry-After'] if klass <= RateLimitError
+
+        klass.new(
+          code: resolved_code,
+          description: resolved_description,
+          status: err['status'],
+          http_status: response&.status,
+          request_id: headers['X-Request-Id'],
+          server_time: headers['X-Server-Time'],
+          retry_after: retry_after,
+          extra: err['extra'],
+          path: path,
+          verb: verb,
+          body: body
+        )
+      end
+
+      private
+
+      def infer_code_from_http(response)
+        return nil unless response
+
+        case response.status
+        when 401 then 401
+        when 403 then 403
+        when 429 then 429
+        else
+          response.status if response.status >= 500
+        end
+      end
+
+      def http_status_description(status)
+        case status
+        when 401 then 'Unauthorized'
+        when 403 then 'Forbidden'
+        when 429 then 'Too Many Requests'
+        when 500.. then 'Internal Server Error'
+        else
+          "HTTP #{status}"
+        end
+      end
+    end
+  end
 
   ##
-  # Raised when a requested resource is not found (HTTP 404).
+  # Raised when Mixin API returns an error response (unmapped or generic codes).
   #
-  class NotFoundError < Error; end
+  class ResponseError < APIError
+    def retryable?
+      code.to_i >= 500
+    end
+  end
+
+  ##
+  # Raised when a requested resource is not found (error code 404).
+  #
+  class NotFoundError < APIError; end
 
   ##
   # Raised when a user is not found (error code 10404).
   #
-  class UserNotFoundError < Error; end
+  class UserNotFoundError < APIError; end
+
+  ##
+  # Raised when authentication fails (error codes 401, 20121).
+  #
+  class UnauthorizedError < APIError; end
+
+  ##
+  # Raised when access is forbidden (error code 403).
+  #
+  class ForbiddenError < APIError; end
+
+  ##
+  # Raised when the API rate limit is exceeded (error code 429).
+  #
+  class RateLimitError < APIError
+    def throttle?
+      true
+    end
+  end
+
+  ##
+  # Raised when request data is invalid (error codes 400, 10002, 20131, 20150).
+  #
+  class ValidationError < APIError; end
+
+  ##
+  # Raised when a resource conflict or capacity limit applies (error codes 20116, 20123, 20125, 20133).
+  #
+  class ConflictError < APIError; end
+
+  ##
+  # Raised for transfer/withdraw amount or fee constraints.
+  #
+  class TransferError < APIError; end
+
+  ##
+  # Raised for transient conditions that may succeed on retry (error codes 10104, 10105).
+  #
+  class TransientError < APIError
+    def retryable?
+      true
+    end
+  end
 
   ##
-  # Raised when authentication fails (HTTP 401).
+  # Raised when the app must be updated (error code 10006).
   #
-  class UnauthorizedError < Error; end
+  class AppUpdateRequiredError < APIError; end
 
   ##
-  # Raised when access is forbidden (HTTP 403).
+  # Raised when an address format is invalid (error code 30102).
   #
-  class ForbiddenError < Error; end
+  class InvalidAddressFormatError < APIError; end
 
   ##
-  # Raised when there is insufficient balance for a transaction (error code 20117).
+  # Raised for server-side failures (error codes 500, 7000, 7001).
   #
-  class InsufficientBalanceError < Error; end
+  class ServerError < APIError
+    def retryable?
+      true
+    end
+  end
+
+  ##
+  # Raised when there is insufficient balance for a transaction (error codes 20117, 20124).
+  #
+  class InsufficientBalanceError < APIError; end
 
   ##
   # Raised when app prepaid billing credit lacks headroom for a billed operation.
@@ -77,8 +239,8 @@ module MixinBot
   class UtxoInsufficientError < InsufficientBalanceError
     attr_reader :total_input, :total_output, :output_size
 
-    def initialize(message, total_input: nil, total_output: nil, output_size: nil)
-      super(message)
+    def initialize(message = nil, total_input: nil, total_output: nil, output_size: nil, **)
+      super(message, **)
       @total_input = total_input
       @total_output = total_output
       @output_size = output_size
@@ -88,12 +250,12 @@ module MixinBot
   ##
   # Raised when there is insufficient pool for a transaction (error code 30103).
   #
-  class InsufficientPoolError < Error; end
+  class InsufficientPoolError < APIError; end
 
   ##
   # Raised when PIN verification fails (error codes 20118, 20119).
   #
-  class PinError < Error; end
+  class PinError < APIError; end
 
   ##
   # Raised when NFO memo format is invalid.
@@ -119,4 +281,16 @@ module MixinBot
   # Raised when invoice format is invalid.
   #
   class InvalidInvoiceFormatError < Error; end
+
+  class << self
+    ##
+    # Canonical retry decision for API and network failures.
+    #
+    def retryable?(error)
+      return true if error.is_a?(Faraday::TimeoutError) || error.is_a?(Faraday::ConnectionFailed)
+      return error.retryable? if error.respond_to?(:retryable?)
+
+      false
+    end
+  end
 end

data/lib/mixin_bot/monitor.rb

@@ -61,16 +61,7 @@ module MixinBot
       end
 
       def check_retryable_error(error)
-        return false if error.nil?
-
-        reason = error.message.to_s.downcase
-        return true if reason.include?('timeout')
-        return true if reason.include?('internal server')
-        return true if reason.include?('insufficient')
-        return true if reason.include?('inputs locked by')
-        return true if reason.include?('by other transaction')
-
-        false
+        MixinBot.retryable?(error)
       end
     end
   end

data/lib/mixin_bot/version.rb

@@ -11,5 +11,5 @@ module MixinBot
   #
   # @see https://semver.org/
   #
-  VERSION = '2.2.2'
+  VERSION = '2.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.2.2
+  version: 2.3.0
 platform: ruby
 authors:
 - an-lee
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-24 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport