diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 2af3515115..7155b7ab55 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -1,5 +1,16 @@
 # *-*- Mode: Python -*-*
 
+##
+#
+# General note concerning the use of guest agent interfaces:
+#
+# "unsupported" is a higher-level error than the errors that individual
+# commands might document. The caller should always be prepared to receive
+# QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't
+# document any failure mode at all.
+#
+##
+
 ##
 #
 # Echo back a unique integer value, and prepend to response a