diff --git a/swh/web/api/views/vault.py b/swh/web/api/views/vault.py
--- a/swh/web/api/views/vault.py
+++ b/swh/web/api/views/vault.py
@@ -82,7 +82,9 @@
 
         :statuscode 200: no error
         :statuscode 400: an invalid directory identifier has been provided
-        :statuscode 404: requested directory can not be found in the archive
+        :statuscode 404: requested directory did not receive any cooking
+            request yet (in case of GET) or can not be found in the archive
+            (in case of POST)
     """
     _, obj_id = query.parse_hash_with_algorithms_or_throws(
         dir_id, ['sha1'], 'Only sha1_git is supported.')
@@ -115,7 +117,9 @@
 
         :statuscode 200: no error
         :statuscode 400: an invalid directory identifier has been provided
-        :statuscode 404: requested directory can not be found in the archive
+        :statuscode 404: requested directory did not receive any cooking
+            request yet (in case of GET) or can not be found in the archive
+            (in case of POST)
     """
     _, obj_id = query.parse_hash_with_algorithms_or_throws(
         dir_id, ['sha1'], 'Only sha1_git is supported.')
@@ -179,7 +183,9 @@
 
         :statuscode 200: no error
         :statuscode 400: an invalid revision identifier has been provided
-        :statuscode 404: requested revision can not be found in the archive
+        :statuscode 404: requested directory did not receive any cooking
+            request yet (in case of GET) or can not be found in the archive
+            (in case of POST)
     """
     _, obj_id = query.parse_hash_with_algorithms_or_throws(
         rev_id, ['sha1'], 'Only sha1_git is supported.')
@@ -212,7 +218,9 @@
 
         :statuscode 200: no error
         :statuscode 400: an invalid revision identifier has been provided
-        :statuscode 404: requested revision can not be found in the archive
+        :statuscode 404: requested directory did not receive any cooking
+            request yet (in case of GET) or can not be found in the archive
+            (in case of POST)
     """
     _, obj_id = query.parse_hash_with_algorithms_or_throws(
         rev_id, ['sha1'], 'Only sha1_git is supported.')