    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