fix: Make invalid, missing param error messages more generic

These errors may refer to form params, not just query string params. Adjust
the response message to the client to make it more generic, in order to
avoid confusion.

Also adjust docstrings for HTTPInvalidXXX and HTTPMissingXXX to be more
informative and consistent.

See issue #549

falcon/errors.py

@@ -369,7 +369,7 @@ def __init__(self, title, description, retry_after, **kwargs):
 
 
 class HTTPInvalidHeader(HTTPBadRequest):
-    """HTTP header is invalid. Inherits from ``HTTPBadRequest``.
+    """A header in the request is invalid. Inherits from ``HTTPBadRequest``.
 
     Args:
         msg (str): A description of why the value is invalid.
@@ -388,7 +388,7 @@ def __init__(self, msg, header_name, **kwargs):
 
 
 class HTTPMissingHeader(HTTPBadRequest):
-    """HTTP header is missing. Inherits from ``HTTPBadRequest``.
+    """A header is missing from the request. Inherits from ``HTTPBadRequest``.
 
     Args:
         header_name (str): The name of the header.
@@ -405,35 +405,41 @@ def __init__(self, header_name, **kwargs):
 
 
 class HTTPInvalidParam(HTTPBadRequest):
-    """HTTP parameter is invalid. Inherits from ``HTTPBadRequest``.
+    """A parameter in the request is invalid. Inherits from ``HTTPBadRequest``.
+
+    This error may refer to a parameter in a query string, form, or
+    document that was submitted with the request.
 
     Args:
         msg (str): A description of the invalid parameter.
-        param_name (str): The name of the paramameter.
+        param_name (str): The name of the parameter.
         kwargs (optional): Same as for ``HTTPError``.
 
     """
 
     def __init__(self, msg, param_name, **kwargs):
-        description = 'The "{0}" query parameter is invalid. {1}'
+        description = 'The "{0}" parameter is invalid. {1}'
         description = description.format(param_name, msg)
 
-        super(HTTPInvalidParam, self).__init__('Invalid query parameter',
+        super(HTTPInvalidParam, self).__init__('Invalid parameter',
                                                description, **kwargs)
 
 
 class HTTPMissingParam(HTTPBadRequest):
-    """HTTP parameter is missing. Inherits from ``HTTPBadRequest``.
+    """A parameter is missing from the request. Inherits from ``HTTPBadRequest``.
+
+    This error may refer to a parameter in a query string, form, or
+    document that was submitted with the request.
 
     Args:
-        param_name (str): The name of the paramameter.
+        param_name (str): The name of the parameter.
         kwargs (optional): Same as for ``HTTPError``.
 
     """
 
     def __init__(self, param_name, **kwargs):
-        description = 'The "{0}" query parameter is required.'
+        description = 'The "{0}" parameter is required.'
         description = description.format(param_name)
 
-        super(HTTPMissingParam, self).__init__('Missing query parameter',
+        super(HTTPMissingParam, self).__init__('Missing parameter',
                                                description, **kwargs)

tests/test_httperror.py

@@ -636,10 +636,10 @@ def test_invalid_param(self):
         self.api.add_route('/400', InvalidParamResource())
         body = self.simulate_request('/400', decode='utf-8')
 
-        expected_desc = (u'The "id" query parameter is invalid. The '
+        expected_desc = (u'The "id" parameter is invalid. The '
                          u'value must be a hex-encoded UUID.')
         expected_body = {
-            u'title': u'Invalid query parameter',
+            u'title': u'Invalid parameter',
             u'description': expected_desc,
             u'code': u'P1002',
         }
@@ -652,8 +652,8 @@ def test_missing_param(self):
         body = self.simulate_request('/400', decode='utf-8')
 
         expected_body = {
-            u'title': u'Missing query parameter',
-            u'description': u'The "id" query parameter is required.',
+            u'title': u'Missing parameter',
+            u'description': u'The "id" parameter is required.',
             u'code': u'P1003',
         }
 

tests/test_query_params.py

@@ -95,8 +95,8 @@ def test_required(self, method_name):
             self.fail('falcon.HTTPMissingParam not raised')
         except falcon.HTTPMissingParam as ex:
             self.assertIsInstance(ex, falcon.HTTPBadRequest)
-            self.assertEqual(ex.title, 'Missing query parameter')
-            expected_desc = 'The "marker" query parameter is required.'
+            self.assertEqual(ex.title, 'Missing parameter')
+            expected_desc = 'The "marker" parameter is required.'
             self.assertEqual(ex.description, expected_desc)
 
     def test_int(self):
@@ -110,8 +110,8 @@ def test_int(self):
         except Exception as ex:
             self.assertIsInstance(ex, falcon.HTTPBadRequest)
             self.assertIsInstance(ex, falcon.HTTPInvalidParam)
-            self.assertEqual(ex.title, 'Invalid query parameter')
-            expected_desc = ('The "marker" query parameter is invalid. '
+            self.assertEqual(ex.title, 'Invalid parameter')
+            expected_desc = ('The "marker" parameter is invalid. '
                              'The value must be an integer.')
             self.assertEqual(ex.description, expected_desc)
 
@@ -203,8 +203,8 @@ def test_boolean(self):
             req.get_param_as_bool('bogus2')
         except Exception as ex:
             self.assertIsInstance(ex, falcon.HTTPInvalidParam)
-            self.assertEqual(ex.title, 'Invalid query parameter')
-            expected_desc = ('The "bogus2" query parameter is invalid. '
+            self.assertEqual(ex.title, 'Invalid parameter')
+            expected_desc = ('The "bogus2" parameter is invalid. '
                              'The value of the parameter must be "true" '
                              'or "false".')
             self.assertEqual(ex.description, expected_desc)
@@ -367,8 +367,8 @@ def test_list_transformer(self):
             req.get_param_as_list('coord', transform=int)
         except Exception as ex:
             self.assertIsInstance(ex, falcon.HTTPInvalidParam)
-            self.assertEqual(ex.title, 'Invalid query parameter')
-            expected_desc = ('The "coord" query parameter is invalid. '
+            self.assertEqual(ex.title, 'Invalid parameter')
+            expected_desc = ('The "coord" parameter is invalid. '
                              'The value is not formatted correctly.')
             self.assertEqual(ex.description, expected_desc)