DhanHQ 2.6.2 → 2.6.3

data/lib/DhanHQ/contracts/forever_order_contract.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    # Validates request for POST /v2/forever/orders (create Forever / GTT order).
+    # orderFlag: SINGLE | OCO. productType: CNC | MTF. For OCO, price1, triggerPrice1, quantity1 required.
+    class ForeverOrderCreateContract < BaseContract
+      params do
+        required(:dhan_client_id).filled(:string)
+        required(:order_flag).filled(:string, included_in?: OrderFlag::ALL)
+        required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+        required(:exchange_segment).filled(:string, included_in?: FOREVER_ORDER_SEGMENTS)
+        required(:product_type).filled(:string, included_in?: FOREVER_ORDER_PRODUCT_TYPES)
+        required(:order_type).filled(:string, included_in?: %w[LIMIT MARKET])
+        required(:validity).filled(:string, included_in?: VALIDITY_TYPES)
+        required(:security_id).filled(:string)
+        required(:quantity).filled(:integer, gt?: 0)
+        required(:price).filled(:float, gt?: 0)
+        required(:trigger_price).filled(:float)
+        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:disclosed_quantity).maybe(:integer, gteq?: 0)
+        optional(:price1).maybe(:float, gt?: 0)
+        optional(:trigger_price1).maybe(:float)
+        optional(:quantity1).maybe(:integer, gt?: 0)
+      end
+
+      rule(:order_flag) do
+        next unless value == DhanHQ::Constants::OrderFlag::OCO
+
+        missing = []
+        missing << "price1" if values[:price1].nil? || values[:price1].to_f <= 0
+        missing << "trigger_price1" if values[:trigger_price1].nil?
+        missing << "quantity1" if values[:quantity1].nil? || values[:quantity1].to_i < 1
+        key.failure("required for OCO: #{missing.join(", ")}") if missing.any?
+      end
+    end
+
+    # Validates request for PUT /v2/forever/orders/{order-id} (modify Forever order).
+    # orderType: LIMIT | MARKET | STOP_LOSS | STOP_LOSS_MARKET. legName: TARGET_LEG | STOP_LOSS_LEG.
+    class ForeverOrderModifyContract < BaseContract
+      params do
+        required(:dhan_client_id).filled(:string)
+        required(:order_id).filled(:string)
+        required(:order_flag).filled(:string, included_in?: OrderFlag::ALL)
+        required(:order_type).filled(:string, included_in?: ORDER_TYPES)
+        required(:leg_name).filled(:string, included_in?: %w[TARGET_LEG STOP_LOSS_LEG])
+        required(:quantity).filled(:integer, gt?: 0)
+        required(:price).filled(:float, gt?: 0)
+        required(:trigger_price).filled(:float)
+        required(:validity).filled(:string, included_in?: VALIDITY_TYPES)
+        optional(:disclosed_quantity).maybe(:integer, gteq?: 0)
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/historical_data_contract.rb

@@ -4,40 +4,38 @@ require "date"
 
 module DhanHQ
   module Contracts
-    # Validates payloads for the historical data endpoints.
+    # Validates payloads for POST /v2/charts/historical (daily OHLC). No interval.
     class HistoricalDataContract < BaseContract
       params do
-        # Common required fields
         required(:security_id).filled(:string)
-        required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+        required(:exchange_segment).filled(:string, included_in?: CHART_EXCHANGE_SEGMENTS)
         required(:instrument).filled(:string, included_in?: INSTRUMENTS)
+        required(:from_date).filled(:string, format?: /\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/)
+        required(:to_date).filled(:string, format?: /\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/)
 
-        # Date range required for both Daily & Intraday
-        required(:from_date).filled(:string, format?: /\A\d{4}-\d{2}-\d{2}\z/)
-        required(:to_date).filled(:string, format?: /\A\d{4}-\d{2}-\d{2}\z/)
-
-        # Optional fields
-        optional(:expiry_code).maybe(:integer, included_in?: [0, 1, 2])
-
-        # For intraday, the user can supply an "interval"
-        # (valid: 1, 5, 15, 25, 60)
-        optional(:interval).maybe(:string, included_in?: %w[1 5 15 25 60])
+        optional(:expiry_code).maybe(:integer, included_in?: ExpiryCode::ALL)
+        optional(:interval).maybe(:string, included_in?: CHART_INTERVALS)
+        optional(:oi).maybe(:bool)
       end
 
       rule(:from_date) do
-        next unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        next unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/)
 
-        d = Date.parse(value)
-        key.failure("must be a valid trading date (no weekend dates)") unless trading_day?(d)
+        # Only validate weekend for pure date strings (YYYY-MM-DD)
+        if value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          d = Date.parse(value)
+          key.failure("must be a valid trading date (no weekend dates)") unless trading_day?(d)
+        end
       rescue Date::Error
         key.failure("invalid date format")
       end
 
       rule(:from_date, :to_date) do
-        next unless values[:from_date].match?(/\A\d{4}-\d{2}-\d{2}\z/) && values[:to_date].match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        next unless values[:from_date].match?(/\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/) &&
+                    values[:to_date].match?(/\A\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?\z/)
 
-        from_date = Date.parse(values[:from_date])
-        to_date = Date.parse(values[:to_date])
+        from_date = DateTime.parse(values[:from_date])
+        to_date = DateTime.parse(values[:to_date])
         key.failure("from_date must be before to_date") if from_date >= to_date
       rescue Date::Error
         key.failure("invalid date format")

data/lib/DhanHQ/contracts/intraday_historical_data_contract.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    # Validates payloads for POST /v2/charts/intraday (minute OHLC). Requires interval.
+    class IntradayHistoricalDataContract < HistoricalDataContract
+      params do
+        required(:interval).filled(:string, included_in?: CHART_INTERVALS)
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/margin_calculator_contract.rb

@@ -2,39 +2,41 @@
 
 module DhanHQ
   module Contracts
-    # Validates requests sent to the margin calculator endpoint.
-    class MarginCalculatorContract < Dry::Validation::Contract
+    # Validates request for POST /v2/margincalculator (single order).
+    # dhanClientId, exchangeSegment (NSE_EQ|NSE_FNO|BSE_EQ|BSE_FNO|MCX_COMM), transactionType, quantity,
+    # productType (CNC|INTRADAY|MARGIN|MTF), securityId, price (required);
+    # orderType (optional, but required by some accounts); triggerPrice (optional, for SL-M/SL-L).
+    class MarginCalculatorContract < BaseContract
       params do
         required(:dhanClientId).filled(:string)
-        required(:exchangeSegment).filled(:string, included_in?: DhanHQ::Constants::ExchangeSegment::ALL)
-        required(:transactionType).filled(:string, included_in?: DhanHQ::Constants::TransactionType::ALL)
+        required(:exchangeSegment).filled(:string, included_in?: MARGIN_CALCULATOR_SEGMENTS)
+        required(:transactionType).filled(:string, included_in?: TRANSACTION_TYPES)
         required(:quantity).filled(:integer, gt?: 0)
-        required(:productType).filled(:string, included_in?: DhanHQ::Constants::ProductType::ALL)
+        required(:productType).filled(:string, included_in?: MARGIN_PRODUCT_TYPES)
+        optional(:orderType).maybe(:string, included_in?: ORDER_TYPES)
         required(:securityId).filled(:string)
-        optional(:price).maybe(:float, gt?: 0)
+        required(:price).filled(:float, gt?: 0)
         optional(:triggerPrice).maybe(:float)
       end
+
       rule(:price) do
-        if values[:price]
-          if values[:price] <= 0
-            key(:price).failure("must be greater than 0")
-          elsif values[:price].is_a?(Float) && (values[:price].nan? || values[:price].infinite?)
-            key(:price).failure("must be a finite number")
-          end
-        end
+        next unless values[:price].is_a?(Float)
+
+        key.failure("must be a finite number") if values[:price].nan? || values[:price].infinite?
       end
 
       rule(:triggerPrice) do
-        key(:triggerPrice).failure("must be a finite number") if values[:triggerPrice].is_a?(Float) && (values[:triggerPrice].nan? || values[:triggerPrice].infinite?)
+        next unless values[:triggerPrice].is_a?(Float)
+
+        key.failure("must be a finite number") if values[:triggerPrice].nan? || values[:triggerPrice].infinite?
       end
 
-      # Segment-Based Product Restrictions for margin calculations
       rule(:productType, :exchangeSegment) do
         case values[:productType]
         when DhanHQ::Constants::ProductType::CNC, DhanHQ::Constants::ProductType::MTF
-          key(:productType).failure("is only allowed for Equity segments (NSE_EQ, BSE_EQ)") unless /_EQ$/.match?(values[:exchangeSegment])
+          key.failure("is only allowed for Equity segments (NSE_EQ, BSE_EQ)") unless values[:exchangeSegment].to_s.end_with?("_EQ")
         when DhanHQ::Constants::ProductType::MARGIN
-          key(:productType).failure("is not allowed for Equity Cash segments; use CNC or INTRADAY") if /_EQ$/.match?(values[:exchangeSegment])
+          key.failure("is not allowed for Equity Cash segments; use CNC or INTRADAY") if values[:exchangeSegment].to_s.end_with?("_EQ")
         end
       end
     end

data/lib/DhanHQ/contracts/market_feed_contract.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    # Validates request payloads for Market Feed endpoints (LTP, OHLC, Quote).
+    #
+    # The Market Feed API expects a payload where keys are Exchange Segments
+    # and values are Arrays of security IDs (Integers).
+    #
+    # @example Valid payload:
+    #   {
+    #     "NSE_EQ": [11536, 3456],
+    #     "NSE_FNO": [49081, 49082]
+    #   }
+    #
+    class MarketFeedContract < BaseContract
+      params do
+        config.validate_keys = true
+
+        # Dynamically define all valid exchange segments as optional keys.
+        # Each must be an array of integers.
+        EXCHANGE_SEGMENTS.each do |segment|
+          optional(segment.to_sym).array(:integer)
+        end
+      end
+
+      rule do
+        base.failure("must provide at least one exchange segment and security ID") if values.to_h.empty?
+
+        total_instruments = 0
+        values.to_h.each do |key, value|
+          if value.is_a?(Array)
+            key(key).failure("must not be empty") if value.empty?
+            total_instruments += value.size
+          end
+        end
+
+        base.failure("cannot fetch more than 1000 instruments in a single request (found #{total_instruments})") if total_instruments > 1000
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/multi_scrip_margin_calc_request_contract.rb

@@ -2,20 +2,23 @@
 
 module DhanHQ
   module Contracts
-    # Validates requests for multi-scrip margin calculations.
+    # Validates request for POST /v2/margincalculator/multi.
+    # Top-level: includePosition, includeOrder, dhanClientId, scripList.
+    # Each scrip: exchangeSegment, transactionType, quantity, productType, securityId, price; triggerPrice optional.
     class MultiScripMarginCalcRequestContract < BaseContract
       params do
         optional(:dhanClientId).maybe(:string)
         optional(:includePosition).maybe(:bool)
         optional(:includeOrder).maybe(:bool)
         required(:scripList).array(:hash) do
-          required(:exchangeSegment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+          required(:exchangeSegment).filled(:string, included_in?: MARGIN_CALCULATOR_SEGMENTS)
           required(:transactionType).filled(:string, included_in?: TRANSACTION_TYPES)
           required(:quantity).filled(:integer, gt?: 0)
-          required(:productType).filled(:string, included_in?: PRODUCT_TYPES)
+          required(:productType).filled(:string, included_in?: MARGIN_PRODUCT_TYPES)
+          optional(:orderType).maybe(:string, included_in?: ORDER_TYPES)
           required(:securityId).filled(:string)
-          optional(:price).maybe(:float, gt?: 0)
-          optional(:triggerPrice).maybe(:float, gt?: 0)
+          required(:price).filled(:float, gt?: 0)
+          optional(:triggerPrice).maybe(:float)
         end
       end
     end

data/lib/DhanHQ/contracts/option_chain_contract.rb

@@ -1,40 +1,38 @@
 # frozen_string_literal: true
 
-require_relative "base_contract"
+require "date"
 
 module DhanHQ
   module Contracts
-    # **Validation contract for fetching option chain data**
-    #
-    # Validates request parameters for fetching option chains.
+    # Validates request for POST /v2/optionchain (option chain by underlying and expiry).
+    # UnderlyingScrip (int), UnderlyingSeg (enum), Expiry (YYYY-MM-DD). Rate limit: 1 request per 3 seconds.
     class OptionChainContract < BaseContract
       params do
-        required(:underlying_scrip).filled(:integer) # Security ID
-        required(:underlying_seg).filled(:string, included_in?: %w[IDX_I NSE_FNO BSE_FNO MCX_FO])
+        required(:underlying_scrip).filled(:integer)
+        required(:underlying_seg).filled(:string, included_in?: OPTION_CHAIN_UNDERLYING_SEGMENTS)
         required(:expiry).filled(:string)
       end
 
       rule(:expiry) do
-        # Ensure the expiry date is in "YYYY-MM-DD" format
-        key.failure("must be in 'YYYY-MM-DD' format") unless value.match?(/^\d{4}-\d{2}-\d{2}$/)
+        next unless value.is_a?(String)
 
-        # Ensure it is a valid date
-        begin
-          parsed_date = Date.parse(value)
-          key.failure("must be a valid date") unless parsed_date.to_s == value
-        rescue ArgumentError
-          key.failure("is not a valid date")
+        unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          key.failure("must be in YYYY-MM-DD format")
+          next
         end
+
+        Date.parse(value)
+      rescue StandardError
+        key.failure("must be a valid date")
       end
     end
 
-    # **Validation contract for fetching option chain expiry list**
-    #
-    # Validates request parameters for fetching expiry lists (expiry not required).
+    # Validates request for POST /v2/optionchain/expirylist (expiry list for an underlying).
+    # UnderlyingScrip (int), UnderlyingSeg (enum). No Expiry.
     class OptionChainExpiryListContract < BaseContract
       params do
-        required(:underlying_scrip).filled(:integer) # Security ID
-        required(:underlying_seg).filled(:string, included_in?: %w[IDX_I NSE_FNO BSE_FNO MCX_FO])
+        required(:underlying_scrip).filled(:integer)
+        required(:underlying_seg).filled(:string, included_in?: OPTION_CHAIN_UNDERLYING_SEGMENTS)
       end
     end
   end

data/lib/DhanHQ/contracts/pnl_based_exit_contract.rb

@@ -13,7 +13,7 @@ module DhanHQ
       end
 
       rule(:profitValue, :lossValue) do
-        key.failure("at least one of profitValue or lossValue must be provided") if !values[:profitValue] && !values[:lossValue]
+        key.failure("at least one of profitValue or lossValue must be provided") unless values[:profitValue] || values[:lossValue]
       end
     end
   end

data/lib/DhanHQ/contracts/slice_order_contract.rb

@@ -31,7 +31,7 @@ module DhanHQ
       # Parameters and validation rules for the slicing order request.
       #
       # @!attribute [r] correlationId
-      #   @return [String] Optional. Identifier for tracking, max length 25 characters.
+      #   @return [String] Optional. Identifier for tracking, max length 30 characters (per orders doc).
       # @!attribute [r] transactionType
       #   @return [String] Required. BUY or SELL.
       # @!attribute [r] exchangeSegment
@@ -39,13 +39,13 @@ module DhanHQ
       #     Must be one of: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM.
       # @!attribute [r] productType
       #   @return [String] Required. Product type for the order.
-      #     Must be one of: CNC, INTRADAY, MARGIN, MTF, CO, BO.
+      #     Must be one of: CNC, INTRADAY, MARGIN, MTF (per orders doc).
       # @!attribute [r] orderType
       #   @return [String] Required. Type of order.
       #     Must be one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_MARKET.
       # @!attribute [r] validity
       #   @return [String] Required. Validity of the order.
-      #     Must be one of: DAY, IOC, GTC, GTD.
+      #     Must be one of: DAY, IOC (per orders doc).
       # @!attribute [r] securityId
       #   @return [String] Required. Security identifier for the order.
       # @!attribute [r] quantity
@@ -59,11 +59,11 @@ module DhanHQ
       # @!attribute [r] afterMarketOrder
       #   @return [Boolean] Optional. Indicates if this is an after-market order.
       # @!attribute [r] amoTime
-      #   @return [String] Optional. Time for after-market orders. Must be one of: OPEN, OPEN_30, OPEN_60.
+      #   @return [String] Optional. Time for after-market orders. Must be one of: PRE_OPEN, OPEN, OPEN_30, OPEN_60.
       # @!attribute [r] boProfitValue
-      #   @return [Float] Optional. Profit value for Bracket Orders, must be > 0 if provided.
+      #   @return [Float] Optional. Profit value for Bracket Orders (not used when productType is CNC/INTRADAY/MARGIN/MTF).
       # @!attribute [r] boStopLossValue
-      #   @return [Float] Optional. Stop-loss value for Bracket Orders, must be > 0 if provided.
+      #   @return [Float] Optional. Stop-loss value for Bracket Orders (not used when productType is CNC/INTRADAY/MARGIN/MTF).
       # @!attribute [r] drvExpiryDate
       #   @return [String] Optional. Expiry date for derivative contracts.
       # @!attribute [r] drvOptionType
@@ -71,21 +71,21 @@ module DhanHQ
       # @!attribute [r] drvStrikePrice
       #   @return [Float] Optional. Strike price for options, must be > 0 if provided.
       params do
-        optional(:correlationId).maybe(:string, max_size?: 25)
+        optional(:correlationId).maybe(:string, max_size?: 30)
         required(:transactionType).filled(:string, included_in?: %w[BUY SELL])
         required(:exchangeSegment).filled(:string,
                                           included_in?: %w[NSE_EQ NSE_FNO NSE_CURRENCY BSE_EQ BSE_FNO BSE_CURRENCY
                                                            MCX_COMM])
-        required(:productType).filled(:string, included_in?: %w[CNC INTRADAY MARGIN MTF CO BO])
+        required(:productType).filled(:string, included_in?: %w[CNC INTRADAY MARGIN MTF])
         required(:orderType).filled(:string, included_in?: %w[LIMIT MARKET STOP_LOSS STOP_LOSS_MARKET])
-        required(:validity).filled(:string, included_in?: %w[DAY IOC GTC GTD])
+        required(:validity).filled(:string, included_in?: %w[DAY IOC])
         required(:securityId).filled(:string)
         required(:quantity).filled(:integer, gt?: 0)
         optional(:disclosedQuantity).maybe(:integer, gteq?: 0)
         optional(:price).maybe(:float, gt?: 0)
         optional(:triggerPrice).maybe(:float, gt?: 0)
         optional(:afterMarketOrder).maybe(:bool)
-        optional(:amoTime).maybe(:string, included_in?: %w[OPEN OPEN_30 OPEN_60])
+        optional(:amoTime).maybe(:string, included_in?: %w[PRE_OPEN OPEN OPEN_30 OPEN_60])
         optional(:boProfitValue).maybe(:float, gt?: 0)
         optional(:boStopLossValue).maybe(:float, gt?: 0)
         optional(:drvExpiryDate).maybe(:string)

data/lib/DhanHQ/core/auth_api.rb

@@ -8,7 +8,7 @@ module DhanHQ
   # This class intentionally lives at the top-level namespace so it autoloads
   # cleanly from `lib/DhanHQ/core/auth_api.rb` with Zeitwerk `collapse`.
   class AuthAPI
-    BASE_URL = "https://auth.dhan.co"
+    BASE_URL = Constants::Urls::AUTH_BASE
 
     def connection
       @connection ||= Faraday.new(url: BASE_URL) do |faraday|

data/lib/DhanHQ/core/base_api.rb

@@ -86,21 +86,21 @@ module DhanHQ
       "#{self.class::HTTP_PATH}#{endpoint}"
     end
 
-    # Format parameters based on API endpoint
+    # Format parameters based on API endpoint. Uses path-based strategy (marketfeed: pass-through,
+    # optionchain: titleize, default: camelize).
     def format_params(endpoint, params)
       full_path = build_path(endpoint)
-      return params if marketfeed_api?(full_path) || params.empty?
+      return params if params.empty?
 
-      optionchain_api?(full_path) ? titleize_keys(params) : camelize_keys(params)
+      param_formatter_for(full_path).call(params)
     end
 
-    # Determines if the API endpoint is for Option Chain
-    def optionchain_api?(endpoint)
-      endpoint.include?("/optionchain")
-    end
+    # Returns a callable that formats params for the given path (Strategy).
+    def param_formatter_for(full_path)
+      return ->(p) { p } if full_path.include?("/marketfeed")
+      return ->(p) { titleize_keys(p) } if full_path.include?("/optionchain")
 
-    def marketfeed_api?(endpoint)
-      endpoint.include?("/marketfeed")
+      ->(p) { camelize_keys(p) }
     end
   end
 end

data/lib/DhanHQ/core/base_model.rb

@@ -145,7 +145,10 @@ module DhanHQ
       def parse_collection_response(response)
         # Some endpoints return arrays, others might return a `[:data]` structure
         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.")
+          DhanHQ.logger&.warn(
+            "[DhanHQ::BaseModel] Unexpected response format for collection: #{response.class}. " \
+            "Expected Array or Hash with :data key."
+          )
           return []
         end
 

data/lib/DhanHQ/core/error_handler.rb

@@ -10,9 +10,9 @@ module DhanHQ
     def self.handle(error)
       case error
       when Dry::Validation::Result
-        raise "Validation Error: #{error.errors.to_h}"
+        raise DhanHQ::ValidationError, "Invalid parameters: #{error.errors.to_h}"
       else
-        raise "Error: #{error.message}"
+        raise DhanHQ::Error, error.message
       end
     end
   end

data/lib/DhanHQ/errors.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
 module DhanHQ
-  # Base error class for all DhanHQ API errors
-  class Error < StandardError; end
+  # Base error class for all DhanHQ API errors.
+  # When raised from API response handling, {#response_body} holds the parsed error payload.
+  class Error < StandardError
+    attr_reader :response_body
+
+    def initialize(message = nil, response_body: nil)
+      super(message)
+      @response_body = response_body
+    end
+  end
 
   # Authentication and access errors
   # Raised when access token cannot be resolved (missing config or provider returned nil).
@@ -36,6 +44,10 @@ module DhanHQ
 
   # Order and market data errors
   class OrderError < Error; end
+
+  # Raised when the 25-modifications-per-order API cap would be exceeded.
+  # Count is tracked per Order instance in this process only (see Order#modify).
+  class ModificationLimitError < Error; end
   # Raised when the API signals an issue with the requested data payload.
   class DataError < Error; end
 

data/lib/DhanHQ/helpers/request_helper.rb

@@ -79,9 +79,10 @@ module DhanHQ
       end
 
       out = payload
-      if path && data_api?(path) && %i[post put patch].include?(method)
+      if path && %i[post put patch].include?(method)
         client_id = DhanHQ.configuration&.client_id
-        if client_id && !payload.key?(:dhanClientId) && !payload.key?("dhanClientId")
+        needs_client_id = data_api?(path) || payload_requires_dhan_client_id?(path)
+        if client_id && needs_client_id && !payload.key?(:dhanClientId) && !payload.key?("dhanClientId")
           out = payload.dup
           if out.keys.any?(String)
             out["dhanClientId"] = client_id
@@ -97,5 +98,13 @@ module DhanHQ
       else req.body = out.to_json
       end
     end
+
+    # True when the path is one where the request body must include dhanClientId (order-api style).
+    def payload_requires_dhan_client_id?(path)
+      return false if path.nil? || path.empty?
+
+      prefixes = DhanHQ::Constants::PAYLOAD_REQUIRES_DHAN_CLIENT_ID_PREFIXES
+      prefixes.any? { |p| path.start_with?(p) }
+    end
   end
 end

data/lib/DhanHQ/helpers/response_helper.rb

@@ -3,6 +3,14 @@
 module DhanHQ
   # Helper mixin for normalising API responses and raising mapped errors.
   module ResponseHelper
+    STATUS_ERROR_FALLBACK = {
+      400 => DhanHQ::InputExceptionError,
+      401 => DhanHQ::InvalidAuthenticationError,
+      403 => DhanHQ::InvalidAccessError,
+      404 => DhanHQ::NotFoundError,
+      429 => DhanHQ::RateLimitError
+    }.freeze
+
     private
 
     # Determines if the API response indicates success.
@@ -53,31 +61,52 @@ module DhanHQ
       end
 
       error_class = DhanHQ::Constants::DHAN_ERROR_MAPPING[error_code]
-
       unless error_class
-        # Log unmapped error codes for investigation
         DhanHQ.logger&.warn("[DhanHQ] Unmapped error code: #{error_code} (status: #{response.status})")
+        error_class = status_fallback_error_class(response.status)
+      end
 
-        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
+      message = build_error_text(error_code, error_message, body)
+      raise error_class.new(message, response_body: body)
+    end
+
+    def status_fallback_error_class(status)
+      STATUS_ERROR_FALLBACK[status] ||
+        (status.between?(500, 599) ? DhanHQ::InternalServerError : DhanHQ::OtherError)
+    end
+
+    def build_error_text(error_code, error_message, body = {})
+      text = if error_code == DhanHQ::Constants::TradingErrorCode::NO_HOLDINGS
+               "#{error_message} (error code: #{error_code})"
+             else
+               "#{error_code}: #{error_message}"
+             end
+
+      extra = extra_error_detail(body)
+      text += " | #{extra}" if extra
+
+      if error_code == DhanHQ::Constants::TradingErrorCode::INPUT_EXCEPTION
+        text += " (API does not return which field failed; check required params and value types for this endpoint.)"
       end
 
-      error_text =
-        if error_code == DhanHQ::Constants::TradingErrorCode::NO_HOLDINGS
-          "#{error_message} (error code: #{error_code})"
-        else
-          "#{error_code}: #{error_message}"
-        end
+      text
+    end
 
-      raise error_class, error_text
+    # Returns any additional error detail from the response body (errors array, details, etc.).
+    def extra_error_detail(body)
+      return nil unless body.is_a?(Hash)
+
+      parts = []
+      if body[:errors].is_a?(Array) && body[:errors].any?
+        parts << body[:errors].join("; ")
+      end
+      if body[:details].is_a?(String) && body[:details].to_s.strip != ""
+        parts << body[:details].to_s
+      end
+      if body[:validationErrors].is_a?(Array) && body[:validationErrors].any?
+        parts << body[:validationErrors].map { |e| e.is_a?(Hash) ? e[:message] || e[:field] : e }.join("; ")
+      end
+      parts.empty? ? nil : parts.join(" ")
     end
 
     # Parses JSON response safely. Converts response body to a hash or array with indifferent access.

data/lib/DhanHQ/helpers/validation_helper.rb

@@ -11,7 +11,9 @@ module DhanHQ
       contract = contract_class.new
       result = contract.call(params)
 
-      raise DhanHQ::Error, "Validation Error: #{result.errors.to_h}" unless result.success?
+      raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}" unless result.success?
+
+      result.to_h
     end
 
     # Validate instance attributes using the defined validation contract
@@ -23,7 +25,7 @@ module DhanHQ
 
       result = contract.call(@attributes)
       @errors = result.errors.to_h unless result.success?
-      raise DhanHQ::Error, "Validation Error: #{@errors}" unless valid?
+      raise DhanHQ::ValidationError, "Invalid parameters: #{@errors}" unless valid?
     end
 
     # Checks if the current instance is valid