More improvements

When to use RAISE in procs

Fix broken links

admin.rst

@@ -271,7 +271,7 @@ In the future we're investigating ways to keep the cache updated without manual
 Alternate URL Structure
 =======================
 
-As discussed in `Singular or Plural`_, there are no special URL forms for singular resources in PostgREST, only operators for filtering. Thus there are no URLs like :code:`/people/1`. It would be specified instead as
+As discussed in :ref:`singular_plural`, there are no special URL forms for singular resources in PostgREST, only operators for filtering. Thus there are no URLs like :code:`/people/1`. It would be specified instead as
 
 .. code:: http
 

api.rst

@@ -233,6 +233,8 @@ The current possibilities are
 
 The server will default to JSON for API endpoints and OpenAPI on the root.
 
+.. _singular_plural:
+
 Singular or Plural
 ------------------
 
@@ -289,7 +291,7 @@ In addition to providing RESTful routes for each table and view, PostgREST allow
 
 .. image:: _static/film.png
 
-As seen above in `vertical_filtering`_ we can request the titles of all films like this:
+As seen above in :ref:`v_filter` we can request the titles of all films like this:
 
 .. code-block:: http
 
@@ -423,6 +425,35 @@ By default, a function is executed with the privileges of the user who calls it.
 
   We are considering allowing GET requests for functions that are marked non-volatile. Allowing GET is important for HTTP caching. However we still must decide how to pass function parameters since request bodies are not allowed. Also some query string arguments are already reserved for shaping/filtering the output.
 
+Raising Errors
+--------------
+
+Stored procedures can return non-200 HTTP status codes by raising SQL exceptions. For instance, here's a saucy function that always errors:
+
+.. code-block:: postgresql
+
+  CREATE OR REPLACE FUNCTION just_fail() RETURNS void
+    LANGUAGE plpgsql
+    AS $$
+  BEGIN
+    RAISE EXCEPTION 'I refuse!'
+      USING DETAIL = 'Pretty simple',
+            HINT = 'There is nothing you can do.';
+  END
+  $$;
+
+Calling the function returns HTTP 400 with the body
+
+.. code-block:: json
+
+  {
+    "message":"I refuse!",
+    "details":"Pretty simple",
+    "hint":"There is nothing you can do.",
+    "code":"P0001"
+  }
+
+You can customize the HTTP status code by raising particular exceptions according to the PostgREST :ref:`error to status code mapping <status_codes>`. For example, :code:`RAISE insufficient_privilege` will respond with HTTP 401/403 as appropriate.
 
 Insertions / Updates
 ====================
@@ -523,6 +554,8 @@ You can use a tool like `Swagger UI <http://swagger.io/swagger-ui/>`_ to create
 
   The OpenAPI information can go out of date as the schema changes under a running server. To learn how to refresh the cache see :ref:`schema_reloading`.
 
+.. _status_codes:
+
 HTTP Status Codes
 =================
 

auth.rst

@@ -270,7 +270,7 @@ PostgREST aims to do one thing well: add an HTTP interface to a PostgreSQL datab
 Schema Isolation
 ================
 
-A PostgREST instance is configured to expose all the tables, views, and stored procedures of a single schema specified in a server configuration file. This means private data or implementation details can go inside a private schema and be invisible to HTTP clients. You can then expose views and stored procedures which insulate the internal details from the outside world. It keeps you code easier to refactor, and provides a natural way to do API `versioning`_. For an example of wrapping a private table with a public view see the `Editing User Info`_ section below.
+A PostgREST instance is configured to expose all the tables, views, and stored procedures of a single schema specified in a server configuration file. This means private data or implementation details can go inside a private schema and be invisible to HTTP clients. You can then expose views and stored procedures which insulate the internal details from the outside world. It keeps you code easier to refactor, and provides a natural way to do API versioning. For an example of wrapping a private table with a public view see the :ref:`public_ui` section below.
 
 SQL User Management
 ===================
@@ -363,6 +363,8 @@ With the table in place we can make a helper to check a password against the enc
   end;
   $$;
 
+.. _public_ui:
+
 Public User Interface
 ---------------------