api.md: clarify response behaviour for ACL POST endpoint

Signed-off-by: Daniel Chung <daniel@tailscale.com>

api.md

@@ -367,10 +367,11 @@ Etag: "e0b2816b418b3f266309d94426ac7668ab3c1fa87798785bf82f1085cc2f6d9c"
 
 #### `POST /api/v2/tailnet/:tailnet/acl` - set ACL for a tailnet
 
-Sets the ACL for the given tailnet. HuJSON and JSON are both accepted inputs. An `If-Match` header can be set to avoid missed updates.
+Sets the ACL for the given domain.
+HuJSON and JSON are both accepted inputs.
+An `If-Match` header can be set to avoid missed updates.
 
-Returns error for invalid ACLs.
+Returns the updated ACL in JSON or HuJSON according to the `Accept` header on success. Otherwise, errors are returned for incorrectly defined ACLs, ACLs with failing tests on attempted updates, and mismatched `If-Match` header and ETag.
-Returns error if using an `If-Match` header and the ETag does not match.
 
 ##### Parameters
 
@@ -380,7 +381,17 @@ Returns error if using an `If-Match` header and the ETag does not match.
 `Accept` - Sets the return type of the updated ACL. Response is parsed `JSON` if `application/json` is explicitly named, otherwise HuJSON will be returned.
 
 ###### POST Body
-ACL JSON or HuJSON (see https://tailscale.com/kb/1018/acls)
+
+The POST body should be a JSON or [HuJSON](https://github.com/tailscale/hujson#hujson---human-json) formatted JSON object.
+An ACL policy may contain the following top-level properties:
+
+* `Groups` - Static groups of users which can be used for ACL rules.
+* `Hosts` - Hostname aliases to use in place of IP addresses or subnets.
+* `ACLs` - Access control lists.
+* `TagOwners` - Defines who is allowed to use which tags.
+* `Tests` - Run on ACL updates to check correct functionality of defined ACLs.
+
+See https://tailscale.com/kb/1018/acls for more information on those properties.
 
 ##### Example
 ```
@@ -411,7 +422,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
 }'
 ```
 
-Response
+Response:
 ```
 // Example/default ACLs for unrestricted connections.
 {
@@ -436,9 +447,25 @@ Response
 }
 ```
 
+Failed test error response:
+```
+{
+    "message": "test(s) failed",
+    "data": [
+        {
+            "user": "user1@example.com",
+            "errors": [
+                "address \"user2@example.com:400\": want: Accept, got: Drop"
+            ]
+        }
+    ]
+}
+```
+
 <a name=tailnet-acl-preview-post></a>
 
 #### `POST /api/v2/tailnet/:tailnet/acl/preview` - preview rule matches on an ACL for a resource
+
 Determines what rules match for a user on an ACL without saving the ACL to the server.
 
 ##### Parameters
@@ -477,7 +504,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl?user=user1@exampl
 }'
 ```
 
-Response
+Response:
 ```
 {"matches":[{"users":["*"],"ports":["*:*"],"lineNumber":19}],"user":"user1@example.com"}
 ```