errors: Add 40340 "Integration target address not permitted"

errors/codes/40340.md

@@ -0,0 +1,24 @@
+---
+code: 40340
+identifier: integration_target_address_not_permitted
+title: Integration target address not permitted
+summary: An integration's target resolved to an IP address that Ably does not connect to, such as a private, loopback, or link-local address. Integrations can only target publicly reachable hosts.
+---
+
+## What you should do
+
+Point the integration at a hostname or IP address that is reachable from the public internet. Retrying does not help while the target resolves to the same address.
+
+If the endpoint is reachable only over a private network connection to Ably, [contact Ably support](https://ably.com/support).
+
+## Why it happens
+
+Ably checks the address an integration's target resolves to, both when the integration is created or updated and each time it connects to the target. It does not connect to private address ranges (such as `10.0.0.0/8` and `192.168.0.0/16`), loopback, link-local, or other reserved addresses.
+
+The target may be a host on an internal network, such as a service inside a private cloud network or a development machine. To test against a local server, expose it at a public address first.
+
+The target's DNS may also have changed after the integration was created, so that its hostname now resolves to a private address. Because the address is checked on every connection, an integration that was working can start failing for this reason.
+
+## What you'll see
+
+Creating or updating the integration fails with HTTP status 403 and the message `Disallowed IP address`. Delivery to an existing integration is not part of the response to the publish that triggered it, so a failure for this reason arrives on the `[meta]log` metachannel, which carries [errors that are not otherwise returned to clients](https://ably.com/docs/metadata-stats/metadata/subscribe#log), and its message includes `Disallowed IP address`.

protocol/errors.json

@@ -437,6 +437,11 @@
       "title": "Account not permitted in this region",
       "summary": "The request reached a region the account is not permitted to use."
     },
+    "40340": {
+      "identifier": "integration_target_address_not_permitted",
+      "title": "Integration target address not permitted",
+      "summary": "An integration's target resolved to an IP address that Ably does not connect to, such as a private, loopback, or link-local address. Integrations can only target publicly reachable hosts."
+    },
     "40400": {
       "identifier": "not_found",
       "title": "Resource not found",