def add_error( code, options = nil )

      options   = Hoodoo::Utilities.stringify( options || {} )
      reference = options[ 'reference' ] || {}
      message   = options[ 'message' ]

      # Make sure nobody uses an undeclared error code.

      raise UnknownCode, "In \#add_error: Unknown error code '#{code}'" unless @descriptions.recognised?( code )

      # If the error description specifies a list of required reference keys,
      # make sure all are present and complain if not.

      description = @descriptions.describe( code )

      required_keys = description[ 'reference' ] || []
      actual_keys   = reference.keys
      missing_keys  = required_keys - actual_keys

      unless missing_keys.empty?
        raise MissingReferenceData, "In \#add_error: Reference hash missing required keys: '#{ missing_keys.join( ', ' ) }'"
      end

      # All good!

      @http_status_code = ( description[ 'status' ] || 200 ).to_i if @errors.empty? # Use first in collection for overall HTTP status code

      error = {
        'code'    => code,
        'message' => message || description[ 'message' ] || code
      }

      ordered_keys   = required_keys + ( actual_keys - required_keys )
      ordered_values = ordered_keys.map { | key | escape_commas( reference[ key ].to_s ) }

      # See #unjoin_and_unescape_commas to undo the join below.

      error[ 'reference' ] = ordered_values.join( ',' ) unless ordered_values.empty?

      @errors << error
    end
def add_error( code, options = nil )

      options   = Hoodoo::Utilities.stringify( options || {} )
      reference = options[ 'reference' ] || {}
      message   = options[ 'message' ]

      # Make sure nobody uses an undeclared error code.

      raise UnknownCode, "In \#add_error: Unknown error code '#{code}'" unless @descriptions.recognised?( code )

      # If the error description specifies a list of required reference keys,
      # make sure all are present and complain if not.

      description = @descriptions.describe( code )

      required_keys = description[ 'reference' ] || []
      actual_keys   = reference.keys
      missing_keys  = required_keys - actual_keys

      unless missing_keys.empty?
        raise MissingReferenceData, "In \#add_error: Reference hash missing required keys: '#{ missing_keys.join( ', ' ) }'"
      end

      # All good!

      @http_status_code = ( description[ 'status' ] || 200 ).to_i if @errors.empty? # Use first in collection for overall HTTP status code

      error = {
        'code'    => code,
        'message' => message || description[ 'message' ] || code
      }

      ordered_keys   = required_keys + ( actual_keys - required_keys )
      ordered_values = ordered_keys.map { | key | escape_commas( reference[ key ].to_s ) }

      # See #unjoin_and_unescape_commas to undo the join below.

      error[ 'reference' ] = ordered_values.join( ',' ) unless ordered_values.empty?

      @errors << error
    end
Create an instance.

 +descriptions+:: (Optional) Hoodoo::ErrorDescriptions instance with
                  service-domain-specific error descriptions added, or
                  omit for a default instance describing +platform+ and
                  +generic+ error domains only.

 Add an error instance to this collection.

 +code+::      Error code in full, e.g. +generic.invalid_state'.

 +options+::   An options Hash, optional.

 The options hash contains symbol keys named as follows, with values as
 described:

 +reference+:: Reference data Hash, optionality depending upon the error
               code and the reference data its error description mandates.
               Provide key/value pairs where (symbol) keys are names from
               the array of description requirements and values are
               strings. All values are concatenated into a single string,
               comma-separated. Commas within values are escaped with a
               backslash; backslash is itself escaped with a backslash.

               You must provide that data at a minimum, but can provide
               additional keys too if you so wish. Required keys are
               always included first, in order of appearance in the
               requirements array of the error declaration, followed by
               any extra values in undefined order.

               See also Hoodoo::ErrorDescriptions::DomainDescriptions#error

 +message+::   Optional human-readable for-developer message, +en-nz+
               locale. Default messages are provided for all errors, but
               if you think you can provide something more informative,
               you can do so through this parameter.

 Example:

     errors.add_error(
       'platform.not_found',
       :message => 'Optional custom message',
       :reference => { :entity_name => 'mandatory reference data' }
     )

 In the above example, the mandatory reference data +entity_name+ comes
 from the description for the 'platform.not_found' message - see the
 Hoodoo::ErrorDescriptions#initialize _implementation_ and Platform API.