add info about response and error objects

Author: mathemancer

docs/docs/api/rpc.md

@@ -45,3 +45,42 @@ To use an RPC function:
       - add_from_known_connection
       - add_from_scratch
       - DBModelReturn
+
+## Responses
+
+### Success
+
+Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 234,
+  "result": <any>
+}
+```
+
+The `result` is whatever was returned by the underlying function.
+
+### Errors
+
+When an error is produced by a call to the RPC endpoint, we produce an error of the following form:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 234,
+  "error": {
+    "code": <int>,
+    "message": <str>
+  }
+}
+```
+
+The `code` is a negative integer. Some codes are produced according to the [JSON-RPC spec](https://www.jsonrpc.org/specification#error_object).
+
+More specific codes are produced according to the following documentation:
+
+---
+
+::: mathesar.rpc.exceptions.error_codes.get_error_code

mathesar/rpc/exceptions/error_codes.py

@@ -3,28 +3,40 @@
 all exceptions that Mathesar could possibly throw.
 
 The purpose is to let us send a code with an error response in case an
-RPC function call fails. The codes are organized by the underlying
-code section that could throw the exception:
+RPC function call fails.
 
-- builtins: -31xxx
-- psycopg or psycopg2: -30xxx
-- django: -29xxx
-- mathesar (our code): -28xxx
-- db (our code): -27xxx
-- SQLAlchemy: -26xxx
-- other: -25xxx
-
-Unknown errors return a "round number" code, so an unknown builtin error
-gets the code 31000.
-
-THESE ENUMs ARE INITIALLY AUTO-GENERATED!
+THESE CODES WERE INITIALLY AUTO-GENERATED!
 """
 from frozendict import frozendict
 
 UNKNOWN_KEY = "UNKNOWN"
 
 
-def get_error_code(err):
+def get_error_code(err: Exception) -> int:
+    """
+    Return an error code, given an exception.
+
+    The code produced will align with expectations of a JSON-RPC
+    endpoint. Additionally, the codes are organized by the underlying
+    section of code that could throw the exception:
+
+    - builtins: -31xxx
+    - psycopg or psycopg2: -30xxx
+    - django: -29xxx
+    - mathesar (our code): -28xxx
+    - db (our code): -27xxx
+    - SQLAlchemy: -26xxx
+    - other: -25xxx
+
+    Unknown errors return a "round number" code, so an unknown `builtins`
+    error gets the code -31000.
+
+    Args:
+        err: the Exception for which we need a code.
+
+    Returns:
+        A negative integer code.
+    """
     err_module = err.__class__.__module__
     err_name = err.__class__.__name__
     if err_module.startswith("builtin"):