Skip to main content

​
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.

​
Cyclic ring-group chain

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.
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

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