diff --git a/api.rst b/api.rst
index 10c82e4dd..7d58bea72 100644
--- a/api.rst
+++ b/api.rst
@@ -673,7 +673,11 @@ Immutable and stable functions
 
 Procedures in PostgreSQL marked with :code:`stable` or :code:`immutable` `volatility <https://www.postgresql.org/docs/current/static/xfunc-volatility.html>`_ can only read, not modify, the database and PostgREST executes them in a read-only transaction compatible for read-replicas. Stable and immutable functions can be called with the HTTP GET verb if desired.
 
-Because ``add_them`` is declared IMMUTABLE, we can alternately call the function with a GET request:
+.. note::
+
+  The volatility marker is a promise about the behavior of the function.  PostgreSQL will let you mark a function that modifies the database as ``immutable/stable`` without failure.  However the function will fail when called through PostgREST since it executes it in a read-only transaction.
+
+Because ``add_them`` was declared IMMUTABLE, we can alternately call the function with a GET request:
 
 .. code-block:: http