> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting: routing and channel misconfiguration

> Resolve 422 INVALID_RING_GROUP_CYCLE, 422 NO_REACHABLE_CHANNEL, and 409 ARCHIVAL_CHANNEL_NOT_ENABLED — three deterministic configuration gates: decode each error, fix the named data or tenant control once, do not retry.

# Troubleshooting: routing and channel misconfiguration

Three codes on send and export paths refuse because of **configuration you
own**, not a provider fault. All three are deterministic — the same request
re-fires the same gate on every attempt — so there is exactly one fix each
time, and retrying before the fix is a wasted loop.

Find the code in the table below, then jump to its section.

| Error code                           | Gate that fired                                                                | Fix you own                                                        | Go to                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| `INVALID_RING_GROUP_CYCLE` (422)     | A ring-group chain forms a loop (A → B → A) or nests deeper than the depth cap | **Flatten the chain or re-order the members**, then re-save        | [Cyclic ring-group chain](#invalid-ring-group-cycle)          |
| `NO_REACHABLE_CHANNEL` (422)         | Pay-by-link delivery found no preferred channel the contact is reachable on    | **Add a reachable channel to the contact** before minting the link | [No reachable pay-by-link channel](#no-reachable-channel)     |
| `ARCHIVAL_CHANNEL_NOT_ENABLED` (409) | An archival export targeted a channel the archival policy does not enable      | **Enable the channel in the archival policy**, then re-dispatch    | [Archival channel not enabled](#archival-channel-not-enabled) |

## Cyclic ring-group chain<a id="invalid-ring-group-cycle" />

On a ring-group create or update, `422 INVALID_RING_GROUP_CYCLE` means the
`members` list you submitted would make the group reachable from itself —
either a real loop (group A lists group B, and group B lists group A, in
any direction) or a chain nested deeper than the depth cap that list
members can follow.

The error appears most often when you re-edit existing groups: renaming or
re-ordering members across two groups can silently introduce a cycle that
only shows up at save time. The `error.details.cyclePath` in the response
lists the member ids that form the loop, for example `A → B → A`.

**Fix — flatten the chain or re-order the members before re-saving:**

1. Open the group and read `members`. Replace any `ring_group` member that
   closes a loop (a group that leads back to this one, or to a parent of
   this one) with that group's concrete destinations — SIP usernames or
   PSTN numbers — so nesting no longer cycles.
2. If the chain is acyclic but too long, re-order the members so the
   nested `ring_group` chains shorten, or move inner destinations onto the
   outer group directly.
3. Re-submit the same `POST /voice/ring-groups` or `PATCH /voice/ring-groups/:id`
   once. The cycle check runs again at write time and passes when the
   chain terminates in concrete destinations within the depth cap.

## No reachable pay-by-link channel<a id="no-reachable-channel" />

On `POST /billing/pay-by-link`, `422 NO_REACHABLE_CHANNEL` means the
request could not pick a delivery channel for the hosted-checkout link:
none of the channels you pass in `preferredChannels` appears in the
`reachableChannels` list, so the link has no path to reach the recipient.
The API does not send a letter, a voicemail, or a fallback guess — it
refuses, and you fix the contact first.

**Fix — add a reachable channel to the contact before the link is minted:**

1. Find the contact and check which channels your integration has marked
   reachable for them (an SMS-capable number, an email address, or
   whichever channels your channel-resolution step computed).
2. Add the channel the contact can actually be reached on — update the
   contact record (for example `PATCH /contacts/{id}`) with the missing
   address or number, and run your channel-resolution step again so the
   `reachableChannels` you pass reflects the corrected contact.
3. Re-submit `POST /billing/pay-by-link` with a `preferredChannels` entry
   that now intersects `reachableChannels`. The selection picks the first
   preferred channel the contact is reachable on.

## Archival channel not enabled<a id="archival-channel-not-enabled" />

On `POST /compliance/archival/export`, `409 ARCHIVAL_CHANNEL_NOT_ENABLED`
means the export targeted a `channel` the archival policy does not include
— or archival was never enabled on the org at all. The export refuses
rather than half-collecting a channel the policy excludes, because an
archival bundle that skips an expected channel is worse than no bundle.

**Fix — enable the channel in the archival policy, then re-dispatch:**

1. Read the current policy with `GET /compliance/archival` and check
   `channels` — the list the export gate crosses.
2. If archival is off entirely, or the channel is missing, upsert the
   policy with `PUT /compliance/archival` naming the channel the export
   asked for (the `channels` field accepts the same channels the export
   accepts).
3. Re-run the same `POST /compliance/archival/export` once. The gate reads
   the policy on every call, so the same export passes once the channel is
   enabled.

## What not to do

* **Do not retry in a loop.** Every one of these gates re-fires on every
  attempt — a 422 or 409 here is deterministic, and only the fix above
  clears it. A retry loop just replays the same refusal.
* **Do not reconfigure a trunk, a provider, or a codec.** None of these
  gates dispatches — the refusal happens before any provider is touched,
  so no provider change will clear it.
* **Do not wait for the gate to expire.** Ring-group cycles, pay-by-link
  reachability, and archival policy gates never age out on their own.
* **Do not ask for a second opinion from the error.** The `details` object
  on the 422 (the `cyclePath`) or the named channel on the 409 is the
  answer — read it, then fix once.

## See also

* [References: error codes](/reference/error-codes) — the error catalog
  these three codes live in.
* [Troubleshooting hub](/reference/troubleshooting-hub) — every runbook
  grouped by surface; pick the one that matches your code.