diff --git a/docs/spec/api.md b/docs/spec/api.md
index cec3402c2..ac2798d51 100644
--- a/docs/spec/api.md
+++ b/docs/spec/api.md
@@ -1129,6 +1129,7 @@ Retrieve information about tags.
 Fetch the tags under the repository identified by `name`.
 
 
+##### Tags
 
 ```
 GET /v2/<name>/tags/list
@@ -1136,7 +1137,7 @@ Host: <registry host>
 Authorization: <scheme> <token>
 ```
 
-
+Return all tags for the repository
 
 
 The following parameters should be specified on the request:
@@ -1155,7 +1156,6 @@ The following parameters should be specified on the request:
 ```
 200 OK
 Content-Length: <length>
-Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
@@ -1238,6 +1238,7 @@ The error codes that may be included in the response body are enumerated below:
 
 
 
+##### Tags Paginated
 
 ```
 GET /v2/<name>/tags/list?n=<integer>last=<integer>
@@ -1262,6 +1263,7 @@ The following parameters should be specified on the request:
 ```
 200 OK
 Content-Length: <length>
+Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
@@ -1285,6 +1287,67 @@ The following headers will be returned with the response:
 
 
 
+###### On Failure: Not Found
+
+```
+404 Not Found
+Content-Type: application/json; charset=utf-8
+
+{
+	"errors:" [
+	    {
+            "code": <error code>,
+            "message": "<error message>",
+            "detail": ...
+        },
+        ...
+    ]
+}
+```
+
+The repository is not known to the registry.
+
+
+
+The error codes that may be included in the response body are enumerated below:
+
+|Code|Message|Description|
+|----|-------|-----------|
+| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
+
+
+
+###### On Failure: Unauthorized
+
+```
+401 Unauthorized
+Content-Type: application/json; charset=utf-8
+
+{
+	"errors:" [
+	    {
+            "code": <error code>,
+            "message": "<error message>",
+            "detail": ...
+        },
+        ...
+    ]
+}
+```
+
+The client does not have access to the repository.
+
+
+
+The error codes that may be included in the response body are enumerated below:
+
+|Code|Message|Description|
+|----|-------|-----------|
+| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. |
+
+
+
+
 
 ### Manifest
 
@@ -3163,7 +3226,6 @@ Request an unabridged list of repositories available.
 ```
 200 OK
 Content-Length: <length>
-Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
@@ -3208,6 +3270,7 @@ The following parameters should be specified on the request:
 ```
 200 OK
 Content-Length: <length>
+Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
 Content-Type: application/json; charset=utf-8
 
 {
diff --git a/registry/api/v2/descriptors.go b/registry/api/v2/descriptors.go
index ee895b722..635cb7f90 100644
--- a/registry/api/v2/descriptors.go
+++ b/registry/api/v2/descriptors.go
@@ -398,6 +398,8 @@ var routeDescriptors = []RouteDescriptor{
 				Description: "Fetch the tags under the repository identified by `name`.",
 				Requests: []RequestDescriptor{
 					{
+						Name:        "Tags",
+						Description: "Return all tags for the repository",
 						Headers: []ParameterDescriptor{
 							hostHeader,
 							authHeader,
@@ -455,6 +457,7 @@ var routeDescriptors = []RouteDescriptor{
 						},
 					},
 					{
+						Name:            "Tags Paginated",
 						Description:     "Return a portion of the tags for the specified repository.",
 						PathParameters:  []ParameterDescriptor{nameParameterDescriptor},
 						QueryParameters: paginationParameters,
@@ -483,6 +486,30 @@ var routeDescriptors = []RouteDescriptor{
 								},
 							},
 						},
+						Failures: []ResponseDescriptor{
+							{
+								StatusCode:  http.StatusNotFound,
+								Description: "The repository is not known to the registry.",
+								Body: BodyDescriptor{
+									ContentType: "application/json; charset=utf-8",
+									Format:      errorsBody,
+								},
+								ErrorCodes: []errcode.ErrorCode{
+									ErrorCodeNameUnknown,
+								},
+							},
+							{
+								StatusCode:  http.StatusUnauthorized,
+								Description: "The client does not have access to the repository.",
+								Body: BodyDescriptor{
+									ContentType: "application/json; charset=utf-8",
+									Format:      errorsBody,
+								},
+								ErrorCodes: []errcode.ErrorCode{
+									ErrorCodeUnauthorized,
+								},
+							},
+						},
 					},
 				},
 			},