diff --git a/doc/source/cli/nova-manage.rst b/doc/source/cli/nova-manage.rst
index e826fca03687..f4ae60f81392 100644
--- a/doc/source/cli/nova-manage.rst
+++ b/doc/source/cli/nova-manage.rst
@@ -80,6 +80,29 @@ Nova Database
     for the purge, then run ``nova-manage db purge --before <date>`` manually
     after archiving is complete.
 
+    **Return Codes**
+
+    .. list-table::
+       :widths: 20 80
+       :header-rows: 1
+
+       * - Return code
+         - Description
+       * - 0
+         - Nothing was archived.
+       * - 1
+         - Some number of rows were archived.
+       * - 2
+         - Invalid value for ``--max_rows``.
+       * - 3
+         - No connection to the API database could be established using
+           :oslo.config:option:`api_database.connection`.
+       * - 4
+         - Invalid value for ``--before``.
+
+    If automating, this should be run continuously while the result is 1,
+    stopping at 0, or use the ``--until-complete`` option.
+
 ``nova-manage db purge [--all] [--before <date>] [--verbose] [--all-cells]``
     Delete rows from shadow tables. Specifying ``--all`` will delete all data from
     all shadow tables. Specifying ``--before`` will delete data from all shadow tables
diff --git a/nova/cmd/manage.py b/nova/cmd/manage.py
index e43eec1515ef..20056e0ff54d 100644
--- a/nova/cmd/manage.py
+++ b/nova/cmd/manage.py
@@ -2622,4 +2622,9 @@ def main():
             pdb.post_mortem()
         else:
             print(_("An error has occurred:\n%s") % traceback.format_exc())
+        # FIXME(mriedem): Some commands, like archive_deleted_rows, return 1
+        # for providing flow control to the caller, e.g. continue while rc=1
+        # until you get rc=0. If we fail in some unexpected way and return 1
+        # here, automation tools could continue indefinitely. This should
+        # probably be 255 instead.
         return 1