SIP termination causes and header limits
Use this reference when interpreting a call termination or preparing optional SIP headers. It describes the platform's cause mapping and default header validation; it is not a complete SIP interoperability or carrier-certification matrix.
Cause values and SIP responses are different
Delphi selects a platform cause, a SIP cause value, and a Q.850 cause value. The SIP cause appears inside the diagnostic Reason header. It is not necessarily the status code of the SIP message carrying that header. For example, a BYE request can carry a SIP cause value of 408 to explain an application timeout.
| Platform cause | SIP cause | Q.850 cause | Meaning |
|---|---|---|---|
conversation_complete | 200 | 16 | Normal application completion |
bot_timeout | 408 | 102 | Application/bot timeout |
stt_error | 503 | 41 | Speech recognition error |
tts_error | 503 | 41 | Speech synthesis error |
internal_failure | 500 | 41 | Internal failure |
policy_rejected | 403 | 21 | Policy rejection |
unknown_number | 404 | 1 | Unknown or invalid destination |
busy | 486 | 17 | Busy destination |
handover | 200 | 16 | Handover or transfer |
The platform can select a cause explicitly or infer one from its application reason. Use the selected cause recorded for the call; do not diagnose the underlying fault from the numeric value alone. For example, STT and TTS failures share the same numeric values.
Diagnostic header formats
For a platform termination or an in-dialog REFER, the generated SIP diagnostic value has this form:
Reason: SIP;cause=408;text="failover_bot_timeout"
For a new outbound transfer INVITE, Delphi generates X-Transfer-Reason instead of reusing the original dialog's Reason header:
X-Transfer-Reason: handover;sip-cause=200;q850-cause=16;text="agent_handover"
These are examples of generated headers, not instructions to override platform-owned signaling. A final response before a call is answered can also carry a platform Reason; there need not be a BYE in that path.
Diagnostic text has control characters replaced by spaces, repeated whitespace collapsed, and a maximum of 256 Unicode characters before quoting. Quotes and backslashes are escaped for the header value. Empty text falls back to the selected cause name.
The termination service also passes the selected Q.850 value to the telephony stack. Header generation and publication are separate from successful delivery to the peer. Use SIP diagnostics to verify the relevant call leg and capture point.
Default optional-header limits
How many optional SIP headers can I send?
These limits apply to the platform's default optional-header budget. They are not a promise that an external carrier or intermediary accepts every message within the budget.
| Check | Default limit | Counting rule |
|---|---|---|
| Optional headers | 47 | The 64-header model reserves 16 standard/platform headers and one platform Reason header |
| Header name | 128 characters | Unicode characters in the name |
| Header value | 4,096 characters | Unicode characters in the value; the line limit below also applies |
| Complete header line | 4,096 characters | Name + : + value + CRLF |
| Combined optional names and values | 12,000 characters | Sum of name and value lengths across the optional set |
| Estimated complete message | 65,000 characters | Optional complete lines plus a default 768-character platform reserve |
The complete-line limit is tighter than the value limit: a 4,096-character value cannot fit in a 4,096-character line once the name and separators are included. These character-based checks are distinct from the separately measured UTF-8 byte count.
The 1,300-character message-size estimate is a warning threshold, not a hard rejection or a guarantee of automatic transport selection. Check the actual transport and peer limits separately.
Protected headers and normalization
Optional headers must not replace SIP routing, dialog, framing, or authentication headers. Protected names include Via, From, To, Call-ID, CSeq, Route, Contact, Content-Length, and Authorization, as well as internal platform headers. This is a representative list, not the complete reserved-name registry.
The final normalization handles names case-insensitively, removes protected headers, replaces invalid name characters, and removes control characters from values. Configuration validation can reject an invalid field before it reaches this stage. The platform-generated Reason is handled separately from the optional set.
If optional termination headers are invalid
In the platform termination path, an optional-header set that exceeds its budget is dropped, and termination proceeds with the platform-generated signaling. Failure to publish the header intent is logged and does not deliberately keep the call connected. This does not guarantee that the downstream hangup succeeds or that the peer receives the diagnostic header.
Do not generalize this termination behavior into a rule that transfer validation ignores invalid input. Consult the action-specific contract for transfer requirements.
For configuration responsibilities, return to SIP and call handling. For a missing header or unexpected cause, follow SIP diagnostics.