Diagnosing SIP 488 Not Acceptable Here Errors in Genesys Cloud Trunk-to-Queue Failover Configurations

How-To-Articles
1

Diagnosing SIP 488 Not Acceptable Here Errors in Genesys Cloud Trunk-to-Queue Failover Configurations

What This Guide Covers

This guide details how to isolate and resolve SIP 488 Not Acceptable Here errors that occur specifically when Genesys Cloud routes calls to a queue via a primary trunk and triggers failover to a secondary trunk. By the end, you will have a deterministic diagnostic workflow to align codec negotiation, media encryption parameters, and failover routing logic so that fallback leg establishment succeeds without signaling rejection.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 2 or CX 3. CX 1 lacks advanced trunk failover routing, granular packet capture filtering, and the media diagnostic APIs required for this workflow.
  • Permissions: Telephony > Trunk > Edit, Telephony > Trunk > View, Architect > Flow > Edit, Administration > Security > View, Reporting > Call Logs > View, Telephony > Packet Capture > View
  • OAuth Scopes: telephony:trunk:read, telephony:trunk:write, architect:flow:read, analytics:call:read, telephony:packetcapture:read
  • External Dependencies: Primary and secondary SIP trunks (carrier or on-premises PBX), Genesys Cloud packet capture access, SIP proxy or firewall allowing UDP 5060/5061 or TCP 5060, valid DTLS/SRTP certificates if encryption is enforced.

The Implementation Deep-Dive

1. Decoding the SIP 488 in the Genesys Signaling Path

A SIP 488 Not Acceptable Here response indicates that the receiving User Agent Server (UAS) or proxy cannot accept the media formats, security parameters, or transport protocols requested in the INVITE. In Genesys Cloud, this error does not originate from the queue itself. It originates from the trunk signaling proxy during the SDP offer/answer exchange. When failover triggers, Genesys Cloud initiates a new INVITE toward the secondary trunk while attempting to preserve or renegotiate the media context established on the primary leg.

To diagnose the error, capture signaling traffic directly from the Genesys Cloud edge. Navigate to Admin > Telephony > Trunks > [Secondary Trunk] > Packet Capture. Apply a filter for sip.Status == 488. Export the raw SIP message and inspect the Content-Type: application/sdp body. The SDP payload contains the exact rejection vector. Look for mismatched m= (media) lines, missing a=rtpmap attributes, or absent a=encryption directives. Compare the SDP in the 488 response against the original INVITE sent by the Genesys proxy. The delta between the two reveals which parameter the secondary trunk rejected.

The Trap: Assuming every 488 error indicates a missing codec. In Genesys failover scenarios, 488 responses frequently originate from security parameter mismatches, asymmetric ICE candidate generation, or missing a=fingerprint attributes when the secondary trunk enforces encryption but the initial call leg negotiated unencrypted RTP. Focusing solely on codec lists while ignoring the SDP security attributes leads to wasted configuration cycles and persistent failover failures.

Architectural Reasoning: Genesys Cloud uses a centralized signaling proxy that evaluates trunk security profiles before forwarding an INVITE. The proxy does not guess missing parameters. If the secondary trunk profile mandates SRTP but the call leg was established over RTP, the proxy returns 488 before the carrier processes the request. The Genesys media processor binds to the security context established at call creation. Failover extends that context rather than resetting it. The signaling path requires explicit SDP alignment between the primary and secondary trunks to prevent rejection.

2. Aligning Trunk Codec Profiles with Queue Media Requirements

Genesys Cloud queues inherit media settings from the routing strategy, but trunks enforce their own codec arrays. During normal operation, the primary trunk negotiates a payload type that satisfies both the caller and the queue. During failover, the secondary trunk must support the exact same payload type. If the queue requires a specific codec for speech analytics, transcription, or recording, that codec must exist in the priority list on both trunks.

Audit the codec configuration using the Genesys Cloud REST API. Execute the following request to retrieve the primary trunk profile:

GET /api/v2/telephony/providers/edge/trunks/{primaryTrunkId}
Authorization: Bearer {access_token}
Accept: application/json

Locate the codecs array in the response. Note the payload type order and the sRtpRequired flag for each entry. Repeat the request for the secondary trunk. Cross-reference the arrays. Any codec present on the primary trunk but absent on the secondary trunk creates a negotiation gap. If the queue media engine forces a fallback to that missing codec during failover, the secondary trunk returns 488.

To remediate a mismatch, use the PATCH endpoint to synchronize the secondary trunk codec list:

PATCH /api/v2/telephony/providers/edge/trunks/{secondaryTrunkId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "codecs": [
    {
      "name": "PCMU",
      "payloadType": 0,
      "clockRate": 8000,
      "channels": 1
    },
    {
      "name": "G722",
      "payloadType": 9,
      "clockRate": 16000,
      "channels": 1
    },
    {
      "name": "OPUS",
      "payloadType": 111,
      "clockRate": 48000,
      "channels": 2,
      "sRtpRequired": true
    }
  ],
  "codecPreferences": ["PCMU", "G722", "OPUS"]
}

Verify the queue media settings under Admin > Routing > Queues > [Queue] > Media Settings. Ensure the queue does not enforce a codec that falls outside the synchronized trunk arrays.

The Trap: Setting the primary trunk to prefer G.711 while configuring the secondary trunk to prefer Opus. During failover, Genesys attempts to renegotiate media. The secondary trunk rejects the Opus preference if the endpoint or queue media engine does not support it, triggering 488. The error appears as a codec mismatch, but the root cause is divergent priority ordering rather than missing payload definitions.

Architectural Reasoning: Genesys Cloud does not perform real-time transcoding for trunk-to-trunk failover. The signaling path requires a single agreed-upon payload type. Divergent codec lists break the SDP offer/answer exchange during failover because the media processor cannot dynamically transcode between trunk legs. The proxy enforces strict payload alignment to prevent media desynchronization and recording corruption.

3. Validating Failover Routing Logic in Architect

Failover routing in Genesys Cloud is typically implemented using the Transfer block or the Make Outbound Call block with fallback paths. When the primary trunk fails, the flow routes to the secondary trunk via a transfer action. The configuration of this action dictates how media context and signaling headers propagate to the new leg.

Inspect the flow version in Architect > Flows > [Flow Name] > Version History. Export the flow definition as JSON. Locate the transfer block responsible for failover. Verify the following properties:

  • transferType: Must be ATTENDED or BLIND based on business requirements.
  • preserveMediaSettings: Must be true if you intend to carry encryption and codec preferences to the secondary trunk.
  • callerId: Must match the secondary trunk’s allowed calling number patterns.

If preserveMediaSettings is set to false, Genesys resets the media profile during failover. This action strips encryption flags, resets codec priority, and forces a fresh SDP negotiation. If the secondary trunk profile lacks the exact parameters expected by the queue’s recording engine, negotiation fails.

The Trap: Configuring failover via a Transfer block with transferType: BLIND while expecting media context preservation. Blind transfers terminate the A-leg and spawn a new B-leg. The new B-leg must negotiate SDP from scratch. If the secondary trunk requires a specific P-Asserted-Identity or Path header that the blind transfer does not carry, the trunk returns 488. The flow appears correct in the UI, but the underlying signaling state machine drops the security context.

Architectural Reasoning: Genesys Cloud maintains media context across attended transfers. Blind transfers terminate the original signaling session and initiate a completely independent INVITE. The new INVITE must satisfy all trunk validation rules independently. If the failover logic relies on implicit context preservation without explicitly setting preserveMediaSettings: true, the media processor defaults to the queue’s baseline media profile. This baseline often lacks the encryption attributes required by enterprise carrier trunks, resulting in 488 rejection.

4. Enforcing Consistent Media Encryption and Transport Parameters

Transport protocol alignment and media encryption consistency are mandatory for successful failover. Genesys Cloud evaluates the security profile of the secondary trunk before routing the failover INVITE. The secondary trunk must support the exact transport and encryption suite negotiated on the primary leg.

Navigate to Admin > Telephony > Trunks > [Trunk] > Security. Verify the following settings match exactly between primary and secondary trunks:

  • Transport Protocol: UDP, TCP, or TLS
  • sRtpRequired: Boolean flag enforcing Secure RTP
  • DTLS Certificate: Uploaded certificate bundle for media encryption
  • IceCandidatePolicy: Host, Relay, or All

If the primary trunk negotiates DTLS/SRTP and the secondary trunk only supports legacy SRTP, the Genesys proxy will not downgrade encryption mid-call. The proxy attempts to maintain DTLS/SRTP during failover. The secondary trunk rejects the INVITE with 488 because it lacks the DTLS capability to accept the a=fingerprint and a=setup attributes.

Validate the security configuration via API:

GET /api/v2/telephony/providers/edge/trunks/{trunkId}/security
Authorization: Bearer {access_token}
Accept: application/json

The response returns the security object containing transport, sRtpRequired, and dtlsCertificateId. Cross-reference these values across both trunks. If sRtpRequired differs, synchronize the flag. If dtlsCertificateId is null on the secondary trunk, upload a valid certificate under Admin > Security > Certificates and assign it to the trunk profile.

The Trap: Mixing DTLS/SRTP on the primary trunk with legacy SRTP on the secondary trunk during failover. Genesys Cloud does not downgrade encryption mid-call. The signaling proxy enforces the highest security level negotiated in the initial leg. When failover triggers, the proxy attempts to maintain DTLS/SRTP, but the secondary trunk profile only supports legacy SRTP, causing immediate 488 rejection. Engineers often assume the platform handles encryption fallback automatically. It does not. The media processor requires explicit profile alignment.

Architectural Reasoning: The Genesys media processor binds to the security context established at call creation. Failover does not reset the security context. It extends it. The secondary trunk must support the exact transport and encryption suite of the primary leg. The signaling proxy validates the a=encryption:srtp and a=key attributes against the trunk security profile. If the secondary trunk lacks the cryptographic material or transport capability, the proxy returns 488 to prevent media leakage or recording corruption.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Asymmetric Codec Negotiation During Failover

  • The failure condition: SIP 488 occurs exclusively when failover triggers. Initial calls to the queue via the primary trunk succeed without error.
  • The root cause: Queue media settings force a fallback codec that exists on the primary trunk but is disabled on the secondary trunk. The Genesys media processor attempts to renegotiate using the queue’s fallback codec during failover. The secondary trunk rejects the payload type.
  • The solution: Align codec arrays via API or UI. Execute PATCH /api/v2/telephony/providers/edge/trunks/{secondaryTrunkId} to update the secondary trunk codec list. Include the missing payload type with matching clockRate and channels. Verify the queue media settings under Admin > Routing > Queues do not enforce a codec outside the synchronized arrays. Replicate the failover scenario and monitor packet capture for sip.Status == 200 instead of 488.

Edge Case 2: SRTP and DTLS Context Mismatch on the Secondary Leg

  • The failure condition: 488 response contains a=encryption:srtp missing in the SDP body, or the reason phrase indicates unsupported media security.
  • The root cause: Primary trunk negotiated DTLS/SRTP. Secondary trunk profile has sRtpRequired: false or missing DTLS certificate. The Genesys proxy attempts to carry the DTLS security context into the failover INVITE. The secondary trunk rejects the INVITE because it cannot validate the a=fingerprint attribute.
  • The solution: Enable sRtpRequired: true on the secondary trunk. Upload matching DTLS certificates under Admin > Security > Certificates. Assign the certificate to the trunk security profile. Validate via packet capture that the failover INVITE contains a=setup:actpass and a=fingerprint:sha-256. Confirm the secondary trunk responds with 183 Session Progress followed by 200 OK.

Edge Case 3: SIP Header Sanitization Stripping Failover Context

  • The failure condition: 488 with reason phrase “Unsupported media type” despite correct codec and encryption alignment. Packet capture shows the INVITE lacks P-Asserted-Identity or Path headers.
  • The root cause: Intermediate SIP proxy or carrier firewall strips vendor-specific or routing headers during failover INVITE transmission. Genesys Cloud relies on P-Asserted-Identity for calling number validation and Path for dialog routing. Header sanitization causes the trunk to reject the call for security validation failure.
  • The solution: Disable header sanitization on the Genesys trunk proxy settings under Admin > Telephony > Trunks > [Trunk] > Advanced. Configure the carrier or on-premises PBX to allow passthrough of P-Asserted-Identity, Path, and X-Genesys- headers. Verify header propagation using packet capture. Ensure the secondary trunk accepts the sanitized INVITE without returning 488.

Official References