Document 403, 404, and 422 type_mismatch errors on bulk contacts (Preview)

The bulk contacts endpoints raise three error responses that were not
documented. Each is reachable through the shared bulk scheduling path but
absent from the spec, so integrators had no way to know to handle them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: VarshSuresh

descriptions/0/api.intercom.io.yaml

@@ -9466,6 +9466,34 @@ paths:
                       message: Access Token Invalid
               schema:
                 "$ref": "#/components/schemas/error"
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              examples:
+                job_closed:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: forbidden
+                      message: job job_v2_1 is closed for new task updates
+              schema:
+                "$ref": "#/components/schemas/error"
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              examples:
+                job_not_found:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: job_not_found
+                      message: job job_v2_1 not found
+              schema:
+                "$ref": "#/components/schemas/error"
         '422':
           description: Unprocessable Entity
           content:
@@ -9485,6 +9513,20 @@ paths:
                     errors:
                     - code: parameter_invalid
                       message: maximum number of contacts per request is 100
+                contacts_not_an_array:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: type_mismatch
+                      message: contacts must be an array
+                contact_not_an_object:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: type_mismatch
+                      message: each contact must be an object
               schema:
                 "$ref": "#/components/schemas/error"
     put:
@@ -9605,6 +9647,34 @@ paths:
                       message: Access Token Invalid
               schema:
                 "$ref": "#/components/schemas/error"
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              examples:
+                job_closed:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: forbidden
+                      message: job job_v2_1 is closed for new task updates
+              schema:
+                "$ref": "#/components/schemas/error"
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              examples:
+                job_not_found:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: job_not_found
+                      message: job job_v2_1 not found
+              schema:
+                "$ref": "#/components/schemas/error"
         '422':
           description: Unprocessable Entity
           content:
@@ -9631,6 +9701,20 @@ paths:
                     errors:
                     - code: parameter_invalid
                       message: maximum number of contacts per request is 100
+                contacts_not_an_array:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: type_mismatch
+                      message: contacts must be an array
+                contact_not_an_object:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: type_mismatch
+                      message: each contact must be an object
               schema:
                 "$ref": "#/components/schemas/error"
   "/contacts/bulk/delete":
@@ -9714,6 +9798,34 @@ paths:
                       message: Access Token Invalid
               schema:
                 "$ref": "#/components/schemas/error"
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              examples:
+                job_closed:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: forbidden
+                      message: job job_v2_1 is closed for new task updates
+              schema:
+                "$ref": "#/components/schemas/error"
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              examples:
+                job_not_found:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: job_not_found
+                      message: job job_v2_1 not found
+              schema:
+                "$ref": "#/components/schemas/error"
         '422':
           description: Unprocessable Entity
           content:
@@ -9740,6 +9852,20 @@ paths:
                     errors:
                     - code: parameter_invalid
                       message: maximum number of contacts per request is 100
+                contacts_not_an_array:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: type_mismatch
+                      message: contacts must be an array
+                contact_not_an_object:
+                  value:
+                    type: error.list
+                    request_id: 2859da57-c83f-405c-8166-240a312442a3
+                    errors:
+                    - code: type_mismatch
+                      message: each contact must be an object
               schema:
                 "$ref": "#/components/schemas/error"
   "/contacts/bulk/{id}":