1 files changed, 54 insertions, 1 deletions
diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md
index 7bbc2029d96..ace41e0e92d 100644
--- a/doc/api/graphql/index.md
+++ b/doc/api/graphql/index.md
@@ -70,7 +70,7 @@ possible.
 The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and
 changes are made to the API in a way that maintains backwards-compatibility.
 
-Occassionally GitLab needs to change the GraphQL API in a way that is not backwards-compatible.
+Occasionally GitLab needs to change the GraphQL API in a way that is not backwards-compatible.
 These changes include the removal or renaming of fields, arguments or other parts of the schema.
 
 In these situations, GitLab follows a [Deprecation and removal process](#deprecation-and-removal-process)
@@ -177,6 +177,59 @@ of a query may be altered.
 
 Requests time out at 30 seconds.
 
+### Spam
+
+GraphQL mutations can be detected as spam. If this happens, a
+[GraphQL top-level error](https://spec.graphql.org/June2018/#sec-Errors) is raised. For example:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Request denied. Spam detected",
+      "locations": [ { "line": 6, "column": 7 } ],
+      "path": [ "updateSnippet" ],
+      "extensions": {
+        "spam": true
+      }
+    }
+  ],
+  "data": {
+    "updateSnippet": {
+      "snippet": null
+    }
+  }
+}
+```
+
+If mutation is detected as potential spam and a CAPTCHA service is configured:
+
+- The `captchaSiteKey` should be used to obtain a CAPTCHA response value using the appropriate CAPTCHA API.
+  Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported.
+- The request can be resubmitted with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set.
+
+```json
+{
+  "errors": [
+    {
+      "message": "Request denied. Solve CAPTCHA challenge and retry",
+      "locations": [ { "line": 6, "column": 7 } ],
+      "path": [ "updateSnippet" ],
+      "extensions": {
+        "needsCaptchaResponse": true,
+        "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
+        "spamLogId": 67
+      }
+    }
+  ],
+  "data": {
+    "updateSnippet": {
+      "snippet": null,
+    }
+  }
+}
+```
+
 ## Reference
 
 The GitLab GraphQL reference [is available](reference/index.md).