Skip to main content
Use this reference to find why pgw answered a request with a given status. The page lists only pgw’s own responses, because responses from the PBX and the app pass through unchanged, with these exceptions:
  • pgw sends 500 Server Internal Error in place of a relayed 503 Service Unavailable, and keeps the other headers, Retry-After included.
  • The PBX’s 408 Request Timeout to a REGISTER reaches the app as 504 Server Time-out.
  • pgw doesn’t relay a 100 Trying. It sends its own.

Responses to apps and PBXs

pgw never answers an ACK. It drops an ACK that fails one of these checks.

Responses to apps

Requests other than REGISTER

pgw doesn’t answer 408 to a request other than INVITE. When the other side doesn’t answer such a request within 32 seconds, the sender’s own transaction times out.

REGISTER

How pgw challenges in managed mode

The 401 challenges follow the upstream’s app_auth:
  • With digest or both, a SHA-256 digest challenge, then an MD5 one, on the same nonce. An upstream whose users come from Kamailio gets only the MD5 challenge.
  • With bearer or both, a Bearer realm="<realm>" challenge after the digest challenges. After a token that pgw refused, it carries error="invalid_token".
  • With stale=true, the password was right, but the nonce expired or was used. The app answers again without asking its user.
The realm is the upstream’s realm. Without one, it’s the domain of the app’s To URI on an upstream with domains or a Kamailio upstream with use_domain, and the upstream’s host otherwise. When an app answers both digest challenges, pgw checks the SHA-256 answer. On a managed upstream with domains, a To domain that the upstream doesn’t serve gets 404 Unknown Domain before any challenge.

What pgw registers at the PBX in managed mode

pgw sends the PBX its own REGISTER, with its own address as the Contact. The contact carries the feature tags of all the user’s devices, such as +sip.video, except +sip.instance and +sip.pnsreg. pgw renews at a random point between 40% and 50% of the PBX’s grant, so that devices that registered together renew apart. After a failed renewal, pgw retries after a random 15 to 30 seconds. Each further failure in a row doubles that wait, up to 5 to 10 minutes. After five refusals of the stored password in a row, pgw removes the device, or every device of the user with per_user, and logs managed binding removed: the upstream refused the stored credentials.

Responses to the PBX

Reason texts of a 480

How pgw answers a REGISTER

What pgw forwards to the PBX

When a woken app registers from a new port, pgw removes the device’s old contact at the PBX in the same REGISTER, so each device keeps one contact.

The 200 OK

The 200 OK to an app’s REGISTER lists the app’s Contact with the expiry that pgw grants, even when the PBX answered with a Contact of its own. The user’s other registrations at the PBX stay in the response. When the app’s REGISTER doesn’t list path in Supported, pgw removes the Path headers from the PBX’s 2xx. The 200 OK carries Feature-Caps with +sip.pns, +sip.pnsreg, and +sip.pnspurr:
  • +sip.pnsreg is the lead time, in seconds before the registration expires, at which pgw sends the refresh push. It is 120 on iOS and 600 on Android, or half the registration’s lifetime when that is shorter, and never more than half the app’s own expiry.
  • In managed mode, +sip.pnsreg is absent when the App’s managed_refresh_push is off.
  • A web app’s 200 OK has no +sip.pnsreg, because pgw sends web apps no refresh push.
When a call that pgw held for the app ended before the app returned, the next 200 OK to the app also carries X-Pgw-Call-Status: <call-id>;ended. The call ended because the caller hung up, the hold ran out, pgw couldn’t send the push, or pgw stopped. pgw reports each call for 5 minutes, and at most the 16 newest calls of a device.

A capability query

A REGISTER whose Contact has pn-provider without pn-prid asks which services pgw supports. pgw stores no binding for it.
  • In passthrough mode, pgw forwards it to the PBX without a Contact, so the PBX authenticates it and registers nothing.
  • In managed mode, pgw answers it itself, after it checks the credentials.
Either way, the 200 OK lists the app’s Contact with the expiry, and its Feature-Caps is *;+sip.pns="<provider>", plus +sip.vapid with the web App’s public key for web push.

A REGISTER without a Contact

A REGISTER without a Contact header asks for the user’s registrations, and changes none at pgw or at the PBX.
  • In passthrough mode, pgw forwards it without Contact, Expires, or Path, and relays the PBX’s answer unchanged, challenges included. A 200 OK lists the user’s registrations at the PBX.
  • In managed mode, pgw answers it itself, after it checks the credentials. The 200 OK lists the devices that pgw holds for the user, each with the rest of its expiry.

A 423 from the PBX

When the PBX answers a REGISTER with 423 Interval Too Brief and a Min-Expires above the expiry that pgw asked for, pgw relays the 423 to the app unchanged. From then on, pgw asks that PBX for the greater of the upstream’s max_expires and the PBX’s Min-Expires, up to one day, so the app’s next REGISTER succeeds. pgw forgets the PBX’s minimum when it restarts. In managed mode, pgw registers with the PBX itself, so it doesn’t relay the 423. It registers again at once with the PBX’s minimum, and tries only once more.

Requests inside a call

pgw relays every request inside a call in both directions, including PRACK, so reliable provisional responses (100rel) work end to end. The Allow header of pgw’s 200 OK to an OPTIONS request lists PRACK. When the PBX sends the app a call with a sips: URI, the Record-Route that pgw adds for the app is a sips: URI.

Next steps

Troubleshooting

Find the cause and fix for a status code that you see.

Settings

Look up the settings that this page names.