> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# SIP responses

> The SIP responses that pgw sends itself, the headers it adds, and when it sends each one.

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

| Status | When |
| - | - |
| `400 Bad Request` | A Via header has no host, for example because its port isn't a number. pgw can't relay the request, so it answers it. |
| `483 Too Many Hops` | The request's Max-Forwards is 0. This includes a REGISTER, which pgw then doesn't forward to the PBX. |
| `420 Bad Extension` | The request has a Proxy-Require header. This includes a REGISTER, which pgw then doesn't forward to the PBX. pgw supports no proxy extension, and lists the tags in `Unsupported`. |
| `200 OK` with `Allow`, `Accept: application/sdp`, `Accept-Encoding: identity`, `Accept-Language: en`, and an empty `Supported` | An OPTIONS request is addressed to pgw itself: its Request-URI is pgw's address, and it has no user part, To tag, or Route header. pgw answers a PBX whose address is in any upstream's `invite_source_cidrs`, and an app on a connection that it registered on. Anyone else gets `403 Forbidden`. |
| `481 Call/Transaction Does Not Exist` | A request arrived in the early dialog of pgw's own `180 Ringing`, or pgw has no binding for the dialog that it belongs to. |
| `408 Request Timeout` | The other side gave no final response to a relayed INVITE: a new call from the app, or a re-INVITE in either direction. pgw cancels the INVITE after 3.5 minutes without a provisional response other than `100 Trying`, and answers `408` when no final response follows within 32 seconds. pgw also answers `408` when the app's connection closed while the INVITE was ringing. |
| `500 Server Internal Error` | pgw couldn't send the request to the other side, or the other side answered `503`. pgw also answers `500` when it can't read its database, and to a request whose handling failed unexpectedly. |
| `503 Service Unavailable` | pgw is stopping. A REGISTER gets `Retry-After: 5`. Every held call gets `503` too. |

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

## Responses to apps

### Requests other than REGISTER

| Status | When |
| - | - |
| `403 Forbidden` | The request came over a connection on which no app registered. A request inside a call gets `403` when it comes from another connection than the one that the app registered on. |
| `400 Push Parameters In Request-URI` | The request has `pn-*` parameters in its Request-URI. Its `Authorization` header repeats the Request-URI, so pgw can't remove them without breaking the password check, and the push token would reach the PBX. Apps put push parameters in the Contact (RFC 8599). |
| `404 Not Found` | The upstream that the device registered through no longer exists. |
| `480 Temporarily Unavailable` with `Warning: 399 <hostname> "sips requires a TLS upstream"` | The request uses `sips:`. pgw doesn't connect to PBXs over TLS, so it can't keep the request secure to the PBX. |
| `503 Service Unavailable` with `Retry-After: 1` | The device exceeded `app_request_rate_per_binding`. |
| `503 Service Unavailable` with `Warning: 399 pgw "upstream transport tls is not supported"` | The device's upstream has the transport `tls`, which pgw doesn't support. pgw forwards nothing to it. |
| `CANCEL` with `Reason: SIP;cause=200;text="Call completed elsewhere"` | Another device of the same user answered a call that pgw rang on every device. The app dismisses its ringing screen, and pgw sends it no missed-call push. A CANCEL from the PBX reaches every device with the PBX's Reason headers. |

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

| Status | When |
| - | - |
| `400 Push Parameters In Request-URI` | The REGISTER has `pn-*` parameters in its Request-URI. pgw doesn't forward it to the PBX. |
| `400 Missing To` or `400 Missing To User` | The REGISTER has no To header, or its To URI has no user part. |
| `400 Bad Request` | The To user has an invalid `%` escape, such as `%zz`. |
| `400 Invalid Wildcard` | The REGISTER has `Contact: *` together with another Contact, or without `Expires: 0`. |
| `400 Too Many Contacts` | The REGISTER has more than one Contact. pgw registers one device per REGISTER. |
| `400 Bad Push Parameters` | The Contact's `pn-*` parameters don't parse. For example, `pn-param` ends in `.remote&voip` and `pn-prid` holds one token without a label. |
| `400 Bad Push Parameters` with `Warning: 399 pgw "push subscription host not allowed"` | A browser's push subscription isn't an `https` URL, or is on a host that `webpush_hosts` doesn't list. |
| `404 Unknown Domain` | No upstream has the Request-URI host as its host or in its `domains`, no wildcard in an upstream's `domains` matches it, and no upstream with a Kamailio user source and `use_domain` has it in its domain table. On a managed upstream that keeps its users apart by domain, pgw also answers `404 Unknown Domain` when the upstream doesn't serve the domain of the To URI. |
| `404 Not Found` | The upstream was deleted while the PBX answered the REGISTER. |
| `401 Unauthorized` with `WWW-Authenticate` challenges | The upstream is in managed mode, and the REGISTER has no credentials for the upstream's realm, has a wrong password or token, or names a user that the upstream doesn't have or has turned off. The realm is the upstream's `realm`, else the user's domain on an upstream that keeps users apart by domain, else the upstream's host. See [How pgw challenges in managed mode](#how-pgw-challenges-in-managed-mode). |
| `403 Forbidden` | The upstream is in managed mode, and the credentials' username isn't the user part of the To URI, a valid token's `sub` names another user than the To URI, or you deleted or turned off the user while the PBX answered. |
| `502 Bad Gateway` with `Warning: 399 pgw "upstream did not keep the Path"` | The upstream has `strict_path` set, and the PBX's `200 OK` didn't keep pgw's Path. pgw removes the registration at the PBX and keeps no binding for the device. |
| `502 Bad Gateway` with `Warning: 399 pgw "upstream refused the stored credentials"` | The upstream is in managed mode, the app's credentials were right, and the PBX refused the password that pgw stores for the user: the password changed at the PBX, or the user's AOR has no room for another contact. |
| `502 Bad Gateway` with `Warning: 399 pgw "upstream answered <status>"` | The upstream is in managed mode, and the PBX answered pgw's REGISTER with another final status than `200` or a refusal of the stored password. |
| `500 Server Internal Error` with `Retry-After: 5` | pgw can't check the REGISTER now: a Kamailio user source doesn't answer, pgw can't fetch the token issuer's keys, a Kamailio domain table hasn't loaded, or two upstreams claim the REGISTER's domain. Nothing counts toward the REGISTER ban. |
| `500 Server Internal Error` with `Retry-After: 5` | The PBX refused the connection for a forwarded REGISTER. |
| `500 Server Internal Error` | The PBX answered the forwarded REGISTER with `503`. The response carries the PBX's own `Retry-After`, and none when the PBX sent none. |
| `500 Server Internal Error` with `Retry-After: 1` | Another REGISTER for the same account changed its registrations while the PBX answered. The app's retry succeeds. |
| `500 Server Internal Error` with `Retry-After: 5` | The app unregistered, and pgw couldn't remove the binding from its database. |
| `503 Service Unavailable` with `Retry-After: 5` | The source address exceeded `register_rate_per_ip`. |
| `503 Service Unavailable` with `Retry-After` set to the rest of the ban | The PBX, or pgw in managed mode, refused `register_auth_failures` REGISTERs from the source address for bad credentials, and pgw banned the address for `register_ban`. pgw doesn't forward the REGISTER to the PBX. A refresh over the connection that registered the same account, with the same username, no credentials, or only a token after the device registered with a token, still goes through. |
| `503 Service Unavailable` with `Warning: 399 pgw "upstream transport tls is not supported"` | The upstream has the transport `tls`, which pgw doesn't support. pgw forwards nothing to it. |
| `504 Server Time-out` | The PBX didn't answer a forwarded REGISTER within 20 seconds. pgw never answers a REGISTER with `408 Request Timeout`. |
| `555 Push Notification Service Not Supported` with `Feature-Caps: *;+sip.pns="apns,fcm,webpush"` | No App in the tenant matches the push parameters, the App was deleted while the PBX answered, or `pn-provider` names a service that pgw doesn't send pushes through. The Feature-Caps lists the services that pgw supports. |

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

| The app sends | pgw answers |
| - | - |
| A wrong password, or the name of an unknown or disabled user | The same `401`. It counts toward the REGISTER ban. |
| A digest username that isn't the user part of the To URI | `403 Forbidden`. It counts toward the ban. |
| Credentials for another realm, such as those that an app cached for the PBX | A new challenge. It doesn't count toward the ban. |
| An expired nonce, such as after a push woke the app | One more `401` with `stale=true`. It doesn't count toward the ban. |

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

| Status | When |
| - | - |
| `100 Trying`, then `180 Ringing` | pgw holds the INVITE and sent the call push. The `180` carries a Contact that routes back through pgw, and has the same To tag as pgw's final response to the INVITE. pgw sends no `180` when the INVITE has `Require: 100rel`, because pgw never sends a reliable provisional response. |
| One final response for a call to a user with several devices | pgw relays the first 2xx, and cancels the other devices. A 6xx from any device is relayed at once. Otherwise, once every device has a final response, pgw relays the most useful one: a 4xx over a 5xx, a 5xx over a 3xx, and among 4xx the lowest, so a device that didn't answer (`480`) wins over one that was busy (`486`). |
| `200 OK` with `Allow` | An OPTIONS request is addressed to a device that has a binding. pgw answers for the app, which may be asleep. A device whose push token is dead gets `404 Not Found`. |
| `403 Forbidden` | A new request came from outside every upstream's `invite_source_cidrs`, or a request inside a call came from neither the binding's upstream nor its app. |
| `404 Not Found` | No binding of the sending upstream matches a new INVITE or OPTIONS request. A PBX reaches only the bindings registered through its own upstream. A new INVITE must either carry as its Route the Path that pgw added to the app's registration, or be sent to the Contact that pgw registered for the device with `masquerade` or managed mode. pgw finds the binding by that route alone, so an INVITE sent straight to the app's contact gets `404`. |
| `480 Temporarily Unavailable` with a `Reason` header | pgw couldn't reach the app. The `Reason` header (RFC 3326) names why. See [Reason texts of a 480](#reason-texts-of-a-480). |
| `480 Temporarily Unavailable` without a `Reason` header | The app's connection closed before pgw could relay a request inside a call, the device's binding was removed between its wake-up and the delivery of the held INVITE, or the app's INVITE transaction ended without a final response. |
| `482 Loop Detected` | A second INVITE with the same Call-ID, From tag, and CSeq arrived for the device while the first is in progress. |
| `486 Busy Here` | pgw holds `max_held_per_binding` calls for the device already, or the device reached `call_push_rate_per_binding`. pgw sends no push for the call. |
| `487 Request Terminated` | The PBX cancelled the INVITE. |
| `503 Service Unavailable` with `Retry-After: 5` | pgw holds `max_held_invites` calls already. |

### Reason texts of a 480

| `Reason` | When |
| - | - |
| `SIP;cause=480;text="device did not wake"` | The app didn't register again within `hold_seconds` after the call push. |
| `SIP;cause=480;text="push failed"` | pgw couldn't send the call push. |
| `SIP;cause=480;text="no answer"` | The app rang for 3.5 minutes without answering. Each provisional response from the app other than `100 Trying` restarts the 3.5 minutes. |
| `SIP;cause=480;text="device has no push"` | A device without an open connection registered without push parameters. |
| `SIP;cause=480;text="push token is invalid"` | The push service reported the device's push token as invalid. pgw also removes the device's binding, so the PBX's next request to it gets `404 Not Found`, and in managed mode pgw unregisters the device at the PBX. On iOS, when only the remote token is invalid, the binding stays, calls still reach the device through its VoIP token, and pgw skips missed-call and refresh pushes. |

## How pgw answers a REGISTER

### What pgw forwards to the PBX

| Contact strategy | The PBX receives |
| - | - |
| `path` | The app's Contact without the push parameters, plus a Path header. Parameters such as `+sip.instance`, `reg-id`, and `q` reach the PBX, so GRUU and SIP outbound work through pgw. pgw sets the Contact's `expires` itself. When the Contact has `reg-id`, pgw's Path URI carries `ob` (RFC 5626). |
| `masquerade` | pgw's own address as the Contact, and no Path. |

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

> [card] [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md)
>
> Find the cause and fix for a status code that you see.

> [card] [Settings](https://docs.pgw.sipmicro.services/reference/settings.md)
>
> Look up the settings that this page names.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.