Add improved error messages for RPC on a stale schema

Error message for a not found RPC.

Unsupported overloaded RPC with the same argument names but different types.

api.rst

@@ -1346,6 +1346,10 @@ You can call overloaded functions with different number of arguments.
 
   GET /rpc/rental_duration?customer_id=232&from_date=2018-07-01 HTTP/1.1
 
+.. important::
+
+  Overloaded functions with the same argument names but different types are not supported.
+
 .. _binary_output:
 
 Binary Output

releases/upcoming.rst

@@ -37,3 +37,7 @@ Changed
 * Docker images are now optimized to be built from the scratch image. This reduces the compressed image size from over 30 MB to about 4 MB.
   For more details, see `Docker image built with Nix <https://github.com/PostgREST/postgrest/tree/main/nix/tools/docker#user-content-docker-image-built-with-nix>`_.
   |br| -- `@monacoremo <https://github.com/monacoremo>`_
+
+* Improved error message for a not found RPC on a stale schema (see :ref:`stale_function_signature`) and for the unsupported case of
+  overloaded functions with the same argument names but different types.
+  |br| -- `@laurenceisla <https://github.com/laurenceisla>`_

schema_cache.rst

@@ -53,6 +53,8 @@ But instead, you get an error message that looks like this:
 
 As you can see, PostgREST couldn't find the newly created foreign key in the schema cache. See the section :ref:`schema_reloading` to solve this issue.
 
+.. _stale_function_signature:
+
 Stale Function Signature
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -71,16 +73,14 @@ Then, you make this request:
 
   GET /rpc/plus_one?num=1 HTTP/1.1
 
-On a stale schema, PostgREST will assume :code:`text` as the default type for the function argument ``num``. Thus, the response you get is:
+Next, PostgREST tries to find the function on the stale schema to no avail:
 
 .. code-block:: json
 
- {
-  "hint":"No function matches the given name and argument types. You might need to add explicit type casts.",
-  "details":null,
-  "code":"42883",
-  "message":"function test.plus_one(num => text) does not exist"
- }
+  {
+    "hint": "If a new function was created in the database with this name and arguments, try reloading the schema cache.",
+    "message": "Could not find the api.plus_one(num) function in the schema cache"
+  }
 
 See the section :ref:`schema_reloading` to solve this issue.