DhanHQ 2.1.8 → 2.2.0

data/docs/live_order_updates.md

@@ -18,7 +18,7 @@ The DhanHQ Ruby client provides comprehensive real-time order update functionali
 ```ruby
 require 'dhan_hq'
 
-# Configure credentials
+# Configure credentials (or use config.access_token_provider for dynamic token; see docs/AUTHENTICATION.md)
 DhanHQ.configure do |config|
   config.client_id = "your_client_id"
   config.access_token = "your_access_token"
@@ -317,3 +317,27 @@ All operations are thread-safe using `Concurrent::Map` and `Concurrent::AtomicBo
 - Connection state management
 
 This ensures safe usage in multi-threaded applications.
+
+## Testing
+
+For comprehensive testing examples and interactive console helpers, see the [Testing Guide](TESTING_GUIDE.md). The guide includes:
+
+- **Order Update WebSocket Testing**: Complete examples for all order update features
+- **Event Handler Testing**: Examples for all event types
+- **Order State Management**: Testing order tracking and querying
+- **Interactive Console Helpers**: Load `bin/test_helpers.rb` for quick test functions
+
+**Quick start in console:**
+```ruby
+# Start console
+bin/console
+
+# Load test helpers
+load 'bin/test_helpers.rb'
+
+# Test order WebSocket
+test_order_websocket(10)        # Test order updates for 10 seconds
+
+# Monitor specific order
+monitor_order("112111182045")   # Monitor order by ID
+```

data/docs/rails_integration.md

@@ -46,6 +46,11 @@ dhanhq:
   ws_user_type: "SELF"                            # optional (SELF or PARTNER)
   partner_id: "your-partner-id"                   # optional when ws_user_type: PARTNER
   partner_secret: "your-partner-secret"           # optional when ws_user_type: PARTNER
+  connect_timeout: 10                             # optional, connection timeout in seconds
+  read_timeout: 30                                # optional, read timeout in seconds
+  write_timeout: 30                               # optional, write timeout in seconds
+  ws_max_tracked_orders: 10000                    # optional, max orders to track in WebSocket
+  ws_max_order_age: 604800                        # optional, max order age in seconds (7 days)
 ```
 
 Create an initializer so your app boots with the correct configuration via
@@ -64,6 +69,11 @@ if (creds = Rails.application.credentials.dig(:dhanhq))
   ENV['DHAN_WS_USER_TYPE'] ||= creds[:ws_user_type]
   ENV['DHAN_PARTNER_ID']    ||= creds[:partner_id]
   ENV['DHAN_PARTNER_SECRET'] ||= creds[:partner_secret]
+  ENV['DHAN_CONNECT_TIMEOUT'] ||= creds[:connect_timeout]&.to_s
+  ENV['DHAN_READ_TIMEOUT'] ||= creds[:read_timeout]&.to_s
+  ENV['DHAN_WRITE_TIMEOUT'] ||= creds[:write_timeout]&.to_s
+  ENV['DHAN_WS_MAX_TRACKED_ORDERS'] ||= creds[:ws_max_tracked_orders]&.to_s
+  ENV['DHAN_WS_MAX_ORDER_AGE'] ||= creds[:ws_max_order_age]&.to_s
 end
 
 # fall back to traditional ENV variables when credentials are not defined
@@ -93,6 +103,25 @@ or enable partner streaming flows:
 Set the variables in ENV (or in credentials copied to ENV) **before** the
 initializer calls `DhanHQ.configure_with_env`.
 
+**Dynamic access token (optional)**
+
+For token rotation without restarting the app (e.g. token stored in DB or refreshed via OAuth), use `access_token_provider` so the token is resolved at request time:
+
+```ruby
+# config/initializers/dhanhq.rb (alternative to static ACCESS_TOKEN)
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"] || Rails.application.credentials.dig(:dhanhq, :client_id)
+  config.access_token_provider = lambda do
+    record = DhanAccessToken.active  # your model or service
+    raise "Dhan token expired or missing" unless record
+    record.access_token
+  end
+  config.on_token_expired = ->(error) { DhanAccessToken.refresh! }  # optional: run before retry
+end
+```
+
+When the API returns 401 or token-expired (error code 807) and `access_token_provider` is set, the client retries the request **once** with a fresh token from the provider. `on_token_expired` is called before that retry so you can refresh your store if needed.
+
 ## 3. Build service objects for REST flows
 
 Wrap trading actions in plain-old Ruby objects so controllers and jobs stay thin:

data/docs/websocket_integration.md

@@ -32,6 +32,7 @@ DhanHQ.configure do |config|
   config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
   config.ws_user_type = ENV["DHAN_WS_USER_TYPE"] || "SELF"
 end
+# For dynamic token at request time (REST + WebSocket), use config.access_token_provider; see docs/AUTHENTICATION.md
 ```
 
 ### 2. Market Feed WebSocket (Recommended for Beginners)
@@ -894,6 +895,27 @@ puts "Market subscriptions: #{market_client.subscriptions}"
 puts "Depth subscriptions: #{depth_client.subscriptions}"
 ```
 
+## Testing
+
+For comprehensive testing examples and interactive console helpers, see the [Testing Guide](TESTING_GUIDE.md). The guide includes:
+
+- **WebSocket Testing**: Market feed, order updates, and market depth examples
+- **Interactive Console Helpers**: Load `bin/test_helpers.rb` for quick test functions
+- **Complete Examples**: Copy-paste examples for all WebSocket features
+
+**Quick start in console:**
+```ruby
+# Start console
+bin/console
+
+# Load test helpers
+load 'bin/test_helpers.rb'
+
+# Test WebSocket connections
+test_websocket(:ticker, 5)      # Test market feed for 5 seconds
+test_order_websocket(5)        # Test order updates for 5 seconds
+```
+
 ## Examples
 
 The gem includes comprehensive examples in the `examples/` directory:

data/lib/DhanHQ/client.rb

@@ -36,38 +36,83 @@ module DhanHQ
     #
     # @param api_type [Symbol] Type of API (`:order_api`, `:data_api`, `:non_trading_api`)
     # @return [DhanHQ::Client] A new client instance.
+    # @raise [DhanHQ::Error] If configuration is invalid or rate limiter initialization fails
     def initialize(api_type:)
+      # Configure from ENV if CLIENT_ID is present (backward compatible behavior)
+      # Validation happens at request time in build_headers, not here
       DhanHQ.configure_with_env if ENV.fetch("CLIENT_ID", nil)
+
       # Use shared rate limiter instance per API type to ensure proper coordination
       @rate_limiter = RateLimiter.for(api_type)
 
-      raise "RateLimiter initialization failed" unless @rate_limiter
+      raise DhanHQ::Error, "RateLimiter initialization failed" unless @rate_limiter
+
+      # Get timeout values from configuration or environment, with sensible defaults
+      connect_timeout = ENV.fetch("DHAN_CONNECT_TIMEOUT", 10).to_i
+      read_timeout = ENV.fetch("DHAN_READ_TIMEOUT", 30).to_i
+      write_timeout = ENV.fetch("DHAN_WRITE_TIMEOUT", 30).to_i
 
       @connection = Faraday.new(url: DhanHQ.configuration.base_url) do |conn|
         conn.request :json, parser_options: { symbolize_names: true }
         conn.response :json, content_type: /\bjson$/
         conn.response :logger if ENV["DHAN_DEBUG"] == "true"
+        conn.options.timeout = read_timeout
+        conn.options.open_timeout = connect_timeout
+        conn.options.write_timeout = write_timeout
         conn.adapter Faraday.default_adapter
       end
     end
 
-    # Sends an HTTP request to the API.
+    # Sends an HTTP request to the API with automatic retry for transient errors.
     #
     # @param method [Symbol] The HTTP method (`:get`, `:post`, `:put`, `:delete`)
     # @param path [String] The API endpoint path.
     # @param payload [Hash] The request parameters or body.
+    # @param retries [Integer] Number of retries for transient errors (default: 3)
     # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] Parsed JSON response.
     # @raise [DhanHQ::Error] If an HTTP error occurs.
-    def request(method, path, payload)
+    def request(method, path, payload, retries: 3)
       @rate_limiter.throttle! # **Ensure we don't hit rate limit before calling API**
 
-      response = connection.send(method) do |req|
-        req.url path
-        req.headers.merge!(build_headers(path))
-        prepare_payload(req, payload, method)
-      end
+      attempt = 0
+      auth_retry_done = false
+      begin
+        response = connection.send(method) do |req|
+          req.url path
+          req.headers.merge!(build_headers(path))
+          prepare_payload(req, payload, method)
+        end
 
-      handle_response(response)
+        handle_response(response)
+      rescue DhanHQ::InvalidAuthenticationError, DhanHQ::InvalidTokenError,
+             DhanHQ::TokenExpiredError, DhanHQ::AuthenticationFailedError => e
+        config = DhanHQ.configuration
+        if !auth_retry_done && config&.access_token_provider
+          auth_retry_done = true
+          config.on_token_expired&.call(e)
+          DhanHQ.logger&.warn("[DhanHQ::Client] Auth failure (#{e.class}), retrying once with fresh token")
+          retry
+        end
+        raise
+      rescue DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError => e
+        attempt += 1
+        if attempt <= retries
+          backoff_time = calculate_backoff(attempt)
+          DhanHQ.logger&.warn("[DhanHQ::Client] Transient error (#{e.class}), retrying in #{backoff_time}s (attempt #{attempt}/#{retries})")
+          sleep(backoff_time)
+          retry
+        end
+        raise
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+        attempt += 1
+        if attempt <= retries
+          backoff_time = calculate_backoff(attempt)
+          DhanHQ.logger&.warn("[DhanHQ::Client] Network error (#{e.class}), retrying in #{backoff_time}s (attempt #{attempt}/#{retries})")
+          sleep(backoff_time)
+          retry
+        end
+        raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}"
+      end
     end
 
     # Convenience wrapper for issuing a GET request.
@@ -113,5 +158,16 @@ module DhanHQ
     def delete(path, params = {})
       request(:delete, path, params)
     end
+
+    private
+
+    # Calculates exponential backoff time
+    #
+    # @param attempt [Integer] Current attempt number (1-based)
+    # @return [Float] Backoff time in seconds
+    def calculate_backoff(attempt)
+      # Exponential backoff: 1s, 2s, 4s, 8s, etc., capped at 30s
+      [2**(attempt - 1), 30].min.to_f
+    end
   end
 end

data/lib/DhanHQ/configuration.rb

@@ -20,6 +20,17 @@ module DhanHQ
     # @return [String, nil] The access token or `nil` if not set.
     attr_accessor :access_token
 
+    # Optional callable (Proc/lambda) that returns the access token at request time.
+    # When set, {#resolved_access_token} calls this instead of using {#access_token}.
+    # @return [Proc, nil]
+    attr_accessor :access_token_provider
+
+    # Optional callable invoked when the API returns 401/token-expired and the client
+    # is about to retry (when {#access_token_provider} is set). Use for logging or
+    # refreshing token in your store before the retry fetches a new token.
+    # @return [Proc, nil]
+    attr_accessor :on_token_expired
+
     # The base URL for API requests.
     # @return [String] The base URL for the DhanHQ API.
     attr_accessor :base_url
@@ -64,6 +75,21 @@ module DhanHQ
     # @return [String, nil]
     attr_accessor :partner_secret
 
+    # Returns the access token to use for this request.
+    # If {#access_token_provider} is set, calls it (no memoization; token per request).
+    # Otherwise returns {#access_token}.
+    # @return [String]
+    # @raise [DhanHQ::AuthenticationError] if provider returns nil/empty or no token is set.
+    def resolved_access_token
+      if access_token_provider
+        token = access_token_provider.call
+        raise DhanHQ::AuthenticationError, "access_token_provider returned nil or empty" if token.nil? || token.to_s.empty?
+        token.to_s
+      else
+        access_token
+      end
+    end
+
     # Initializes a new configuration instance with default values.
     #
     # @example

data/lib/DhanHQ/constants.rb

@@ -171,7 +171,7 @@ module DhanHQ
       "804" => DhanHQ::Error, # Too many instruments
       "805" => DhanHQ::RateLimitError, # Too many requests
       "806" => DhanHQ::DataError, # Data API not subscribed
-      "807" => DhanHQ::InvalidTokenError, # Token expired
+      "807" => DhanHQ::TokenExpiredError, # Token expired
       "808" => DhanHQ::AuthenticationFailedError, # Auth failed
       "809" => DhanHQ::InvalidTokenError, # Invalid token
       "810" => DhanHQ::InvalidClientIDError, # Invalid Client ID

data/lib/DhanHQ/contracts/expired_options_data_contract.rb

@@ -10,8 +10,8 @@ module DhanHQ
     class ExpiredOptionsDataContract < BaseContract
       params do
         required(:exchange_segment).filled(:string)
-        required(:interval).filled(:integer)
-        required(:security_id).filled(:string)
+        required(:interval).filled(:string)
+        required(:security_id).filled(:integer)
         required(:instrument).filled(:string)
         required(:expiry_flag).filled(:string)
         required(:expiry_code).filled(:integer)
@@ -28,7 +28,7 @@ module DhanHQ
       end
 
       rule(:interval) do
-        valid_intervals = [1, 5, 15, 25, 60]
+        valid_intervals = %w[1 5 15 25 60]
         key.failure("must be one of: #{valid_intervals.join(", ")}") unless valid_intervals.include?(value)
       end
 
@@ -69,10 +69,10 @@ module DhanHQ
             from_date = Date.parse(values[:from_date])
             to_date = Date.parse(values[:to_date])
 
-            key.failure("from_date must be before to_date") if from_date >= to_date
+            key.failure("from_date must be on or before to_date") if from_date > to_date
 
-            # Check if date range is not too large (max 30 days)
-            key.failure("date range cannot exceed 30 days") if (to_date - from_date).to_i > 30
+            # Check if date range is not too large (max 31 days; to_date is non-inclusive)
+            key.failure("date range cannot exceed 31 days") if (to_date - from_date).to_i > 31
 
             # Check if from_date is not too far in the past (max 5 years)
             five_years_ago = Date.today - (5 * 365)

data/lib/DhanHQ/contracts/place_order_contract.rb

@@ -93,6 +93,57 @@ module DhanHQ
         optional(:drv_strike_price).maybe(:float, gt?: 0)
       end
 
+      # Validate that float values are finite (not NaN or Infinity) and within reasonable bounds
+      rule(:price) do
+        if values[:price].is_a?(Float)
+          if values[:price].nan? || values[:price].infinite?
+            key(:price).failure("must be a finite number")
+          elsif values[:price] > 1_000_000_000
+            key(:price).failure("must be less than 1,000,000,000")
+          end
+        end
+      end
+
+      rule(:trigger_price) do
+        if values[:trigger_price].is_a?(Float)
+          if values[:trigger_price].nan? || values[:trigger_price].infinite?
+            key(:trigger_price).failure("must be a finite number")
+          elsif values[:trigger_price] > 1_000_000_000
+            key(:trigger_price).failure("must be less than 1,000,000,000")
+          end
+        end
+      end
+
+      rule(:bo_profit_value) do
+        if values[:bo_profit_value].is_a?(Float)
+          if values[:bo_profit_value].nan? || values[:bo_profit_value].infinite?
+            key(:bo_profit_value).failure("must be a finite number")
+          elsif values[:bo_profit_value] > 1_000_000_000
+            key(:bo_profit_value).failure("must be less than 1,000,000,000")
+          end
+        end
+      end
+
+      rule(:bo_stop_loss_value) do
+        if values[:bo_stop_loss_value].is_a?(Float)
+          if values[:bo_stop_loss_value].nan? || values[:bo_stop_loss_value].infinite?
+            key(:bo_stop_loss_value).failure("must be a finite number")
+          elsif values[:bo_stop_loss_value] > 1_000_000_000
+            key(:bo_stop_loss_value).failure("must be less than 1,000,000,000")
+          end
+        end
+      end
+
+      rule(:drv_strike_price) do
+        if values[:drv_strike_price].is_a?(Float)
+          if values[:drv_strike_price].nan? || values[:drv_strike_price].infinite?
+            key(:drv_strike_price).failure("must be a finite number")
+          elsif values[:drv_strike_price] > 1_000_000_000
+            key(:drv_strike_price).failure("must be less than 1,000,000,000")
+          end
+        end
+      end
+
       # Custom validation for trigger price when the order type is STOP_LOSS or STOP_LOSS_MARKET.
       rule(:trigger_price, :order_type) do
         if values[:order_type] =~ /^STOP_LOSS/ && !values[:trigger_price]

data/lib/DhanHQ/core/base_model.rb

@@ -143,10 +143,13 @@ module DhanHQ
       # @return [Array<BaseModel>]
       def parse_collection_response(response)
         # Some endpoints return arrays, others might return a `[:data]` structure
-        return [] unless response.is_a?(Array) || (response.is_a?(Hash) && response[:data].is_a?(Array))
+        unless response.is_a?(Array) || (response.is_a?(Hash) && response[:data].is_a?(Array))
+          DhanHQ.logger&.warn("[DhanHQ::BaseModel] Unexpected response format for collection: #{response.class}. Expected Array or Hash with :data key.")
+          return []
+        end
 
         collection = response.is_a?(Array) ? response : response[:data]
-        collection.map { |record| new(record) }
+        collection.map { |record| new(record, skip_validation: true) }
       end
     end
 
@@ -155,11 +158,15 @@ module DhanHQ
     # Update an existing resource
     #
     # @param attributes [Hash] Attributes to update
-    # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject]
+    # @return [DhanHQ::BaseModel, DhanHQ::ErrorObject] Updated model instance or ErrorObject on failure
     def update(attributes = {})
       response = self.class.resource.put("/#{id}", params: attributes)
 
-      success_response?(response) ? self.class.build_from_response(response) : DhanHQ::ErrorObject.new(response)
+      if success_response?(response)
+        self.class.build_from_response(response)
+      else
+        DhanHQ::ErrorObject.new(response)
+      end
     end
 
     # Persists the current resource by delegating to {#create} or {#update}.
@@ -196,10 +203,7 @@ module DhanHQ
     #
     # @return [Boolean] True when the server confirms deletion.
     def delete
-      response = self.class.resource.delete("/#{id}")
-      success_response?(response)
-    rescue StandardError
-      false
+      destroy
     end
 
     # Alias for {#delete} maintained for ActiveModel familiarity.
@@ -208,7 +212,8 @@ module DhanHQ
     def destroy
       response = self.class.resource.delete("/#{id}")
       success_response?(response)
-    rescue StandardError
+    rescue StandardError => e
+      DhanHQ.logger&.error("[DhanHQ::BaseModel] Error deleting resource #{id}: #{e.class} #{e.message}")
       false
     end
 
@@ -222,16 +227,26 @@ module DhanHQ
 
     # Format request parameters before sending to API
     #
+    # Auto-injects dhan_client_id from configuration if not present in attributes
+    # and the model requires it (has dhan_client_id as an attribute).
+    #
     # @return [Hash] The camelCased attributes
     def to_request_params
-      optionchain_api? ? titleize_keys(@attributes) : camelize_keys(@attributes)
+      attrs = @attributes.dup
+      # Auto-inject dhan_client_id from configuration if not provided and model supports it
+      if self.class.defined_attributes&.include?("dhan_client_id") && !attrs[:dhan_client_id] && DhanHQ.configuration.client_id
+        attrs[:dhan_client_id] = DhanHQ.configuration.client_id
+      end
+      optionchain_api? ? titleize_keys(attrs) : camelize_keys(attrs)
     end
 
     # Identifier inferred from the loaded attributes.
     #
     # @return [String, Integer, nil]
     def id
-      @attributes[:id] || @attributes[:order_id] || @attributes[:security_id]
+      id_value = @attributes[:id] || @attributes[:order_id] || @attributes[:security_id]
+      # Convert to string for consistency, but preserve nil
+      id_value&.to_s
     end
 
     # Dynamically assign attributes as methods

data/lib/DhanHQ/errors.rb

@@ -5,6 +5,8 @@ module DhanHQ
   class Error < StandardError; end
 
   # Authentication and access errors
+  # Raised when access token cannot be resolved (missing config or provider returned nil).
+  class AuthenticationError < Error; end
   # DH-901
   class InvalidAuthenticationError < Error; end
   # DH-902
@@ -13,6 +15,8 @@ module DhanHQ
   class UserAccountError < Error; end
   # DH-808
   class AuthenticationFailedError < Error; end
+  # DH-807: token expired (detected from API response; use with retry-on-401)
+  class TokenExpiredError < Error; end
   # DH-807, DH-809
   class InvalidTokenError < Error; end
   # DH-810

data/lib/DhanHQ/helpers/request_helper.rb

@@ -25,22 +25,37 @@ module DhanHQ
     #
     # @param path [String] The API endpoint path.
     # @return [Hash] The request headers.
+    # @raise [DhanHQ::InvalidAuthenticationError] If required headers are missing
     def build_headers(path)
       # Public CSV endpoint for segment-wise instruments requires no auth
       return { "Accept" => "text/csv" } if path.start_with?("/v2/instrument/")
 
+      token = resolved_access_token
+      raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
+
       headers = {
         "Content-Type" => "application/json",
         "Accept" => "application/json",
-        "access-token" => DhanHQ.configuration.access_token
+        "access-token" => token
       }
 
       # Add client-id for DATA APIs
-      headers["client-id"] = DhanHQ.configuration.client_id if data_api?(path)
+      if data_api?(path)
+        client_id = DhanHQ.configuration&.client_id
+        unless client_id
+          raise DhanHQ::InvalidAuthenticationError,
+                "client_id is required for DATA APIs but not set. Please configure DhanHQ with CLIENT_ID."
+        end
+        headers["client-id"] = client_id
+      end
 
       headers
     end
 
+    def resolved_access_token
+      DhanHQ.configuration&.resolved_access_token
+    end
+
     # Determines if the API path requires a `client-id` header.
     #
     # @param path [String] The API endpoint path.

data/lib/DhanHQ/helpers/response_helper.rb

@@ -29,7 +29,12 @@ module DhanHQ
     # @raise [DhanHQ::Error] If an HTTP error occurs.
     def handle_response(response)
       case response.status
-      when 200..299 then parse_json(response.body)
+      when 200..201 then parse_json(response.body)
+      when 202
+        # 202 Accepted is used for async operations (e.g., position conversion)
+        # Return status hash to indicate success for async operations
+        { status: "accepted" }.with_indifferent_access
+      when 203..299 then parse_json(response.body)
       else handle_error(response)
       end
     end
@@ -49,16 +54,21 @@ module DhanHQ
 
       error_class = DhanHQ::Constants::DHAN_ERROR_MAPPING[error_code]
 
-      error_class ||=
-        case response.status
-        when 400 then DhanHQ::InputExceptionError
-        when 401 then DhanHQ::InvalidAuthenticationError
-        when 403 then DhanHQ::InvalidAccessError
-        when 404 then DhanHQ::NotFoundError
-        when 429 then DhanHQ::RateLimitError
-        when 500..599 then DhanHQ::InternalServerError
-        else DhanHQ::OtherError
-        end
+      unless error_class
+        # Log unmapped error codes for investigation
+        DhanHQ.logger&.warn("[DhanHQ] Unmapped error code: #{error_code} (status: #{response.status})")
+
+        error_class =
+          case response.status
+          when 400 then DhanHQ::InputExceptionError
+          when 401 then DhanHQ::InvalidAuthenticationError
+          when 403 then DhanHQ::InvalidAccessError
+          when 404 then DhanHQ::NotFoundError
+          when 429 then DhanHQ::RateLimitError
+          when 500..599 then DhanHQ::InternalServerError
+          else DhanHQ::OtherError
+          end
+      end
 
       error_text =
         if error_code == "DH-1111"
@@ -74,13 +84,24 @@ module DhanHQ
     #
     # @param body [String, Hash] The response body.
     # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] The parsed JSON.
+    # @raise [DhanHQ::DataError] If JSON parsing fails (only for truly invalid JSON, not empty responses)
     def parse_json(body)
       parsed_body =
         if body.is_a?(String)
+          # Handle empty strings gracefully (backward compatible)
+          return {}.with_indifferent_access if body.strip.empty?
+
           begin
             JSON.parse(body, symbolize_names: true)
-          rescue JSON::ParserError
-            {} # Return an empty hash if the string is not valid JSON
+          rescue JSON::ParserError => e
+            # Log error but maintain backward compatibility for edge cases
+            # Only raise for clearly malformed JSON, not for empty/whitespace responses
+            DhanHQ.logger&.error("[DhanHQ] JSON parse error: #{e.message}")
+            DhanHQ.logger&.debug("[DhanHQ] Failed to parse body (first 200 chars): #{body[0..200]}")
+
+            # Raise DataError for invalid JSON (this is an improvement, not a breaking change)
+            # The API should never return invalid JSON, so this helps catch API issues
+            raise DhanHQ::DataError, "Failed to parse JSON response: #{e.message}"
           end
         else
           body