Skip to content
FlySIPFlySIP Docs

Reason header mapping

When a call fails, the caller’s equipment sees a SIP code and, optionally, a Reason header (RFC 3326) with the underlying cause, for example Reason: Q.850; cause=17; text="User busy". Many customers’ switches decide on failover or announcements from these values. FlySIP lets you change both: which SIP code the caller receives, and which Reason header comes with it.

How it works

Section titled “How it works”

Two tables in Tools & Debugs translate codes. Each entry maps an In Code to an Out Code with a reason phrase, and can add a Reason header.

Table Translates Applies to
Result Code Internal Failures the switch generates itself: internal codes such as -20 and SIP codes the switch sends, for example 403 on failed authentication Every caller
Result Code External Responses received from vendors Callers whose account has the selected Account Class
  1. A failure occurs. Either the switch refuses the call or a vendor answers with an error, and hunting has no more routes to try.
  2. The switch looks up the code. For its own failures it checks Result Code Internal. For a vendor’s response it checks Result Code External, but only the entries of the caller account’s Account Class. Accounts without an account class get no external translation.
  3. The code is replaced. Out Code and Reason replace the SIP code and the reason phrase sent to the caller. An empty Reason keeps the original phrase.
  4. The Reason header is set. Under RFC3326 Parameters, Protocol Q.850 or SIP with Cause and Reason builds the header. Disabled adds none. Without an entry, a vendor’s own Reason header goes to the caller unchanged, and for its own failures the switch generates a Q.850 cause where one fits the internal error.
  5. Optionally, a prompt plays. An external entry with an IVR Prompt plays the prompt to the caller first and then sends the translated failure.

The switch reloads both tables about once a minute, so a change applies to new calls without a restart. Translations also apply to provisional responses that match an In Code.

Screenshot "admin-panel/result-code-external-form" has not been generated yet — see scripts/screenshots/screens.yml.

Key terms

Section titled “Key terms”
  • Disconnect cause — the reason a call ended, shown in CDRs as a SIP/Q.850 code.
  • Account — a SIP identity (username/password or IP) owned by a customer that originates and receives calls and carries its own balance.
  • Hunting — trying the next route after a failed attempt.
  • Prompt — a recorded voice message played by an IVR application.

Common scenarios

Section titled “Common scenarios”

A customer’s switch stops at 404 instead of trying its next carrier

Section titled “A customer’s switch stops at 404 instead of trying its next carrier”

Create an Account Class for this customer’s accounts and an external entry with In Code 404, Out Code 503. The customer’s switch now treats the failure as temporary and fails over. Other customers keep the vendor’s 404.

A customer needs a Q.850 cause on every failure

Section titled “A customer needs a Q.850 cause on every failure”

Add external entries for the codes the customer cares about, with Protocol Q.850 and the cause from a published mapping such as ITU-T Q.1912.5. For example, In Code 486, Out Code 486, Cause 17, Reason User busy sends:

SIP/2.0 486 Busy Here
Reason: Q.850; cause=17; text="User busy"

Calls rejected for lack of funds should explain why

Section titled “Calls rejected for lack of funds should explain why”

Add an internal entry with In Code -20 (insufficient balance) and an Out Code and Reason your customers’ equipment understands, for example 402 Payment Required. The internal codes are listed in Calls fail with a SIP error code.

Section titled “Related pages”