Skip to main content

​
Troubleshooting: SIP_CREDENTIAL_NOT_REGISTERED on click-to-call

​
Symptom

A click-to-call request that names a SIP credential returns HTTP 412 with the code SIP_CREDENTIAL_NOT_REGISTERED instead of placing the call. The refusal is a pre-flight check: the call is never dialed, never queued, and never billed. The response body carries the facts this page works with:

​
What it means

A SIP credential is the login a single desk phone or softphone (Bria, Linphone, Zoiper, or the browser softphone) uses to attach to Orbit. Click-to-call rings that device, so it must hold a live registration at the moment you dial. While the client is running and reachable, its keepalive refreshes the registration; when the refreshes stop, the binding ages out. The platform refuses to dial when the newest registration is missing or older than the staleness window: five minutes, delivered exactly as details.stale_threshold_seconds. A device that has not re-registered inside that window is unreachable in practice, and an invite to its expired contact would only die mid-dial, so the refusal names the dead device at request time instead. Read details.last_register_at against the current time. A delta larger than details.stale_threshold_seconds means the device went quiet; null means it never completed a first registration. Either way the fix lives on the client side, in the ladder below.

​
Fix ladder

Work the ladder top-down and stop the moment the softphone shows Registered, then re-dial: a successful registration refreshes last_register_at immediately, so the refusal clears at once.
  1. Confirm the Register toggle is on, per client.
    • Bria: open the account settings and confirm the account is active and set to register; a disabled account never sends REGISTER.
    • Linphone: open the SIP account and confirm its enable toggle is on; disabled accounts stay unregistered silently.
    • Zoiper: confirm the account is enabled under Settings → Accounts; a paused account drops its registration and does not retry.
  2. Re-enter the credential. Compare the account’s username and password with what Settings → Voice shows for this credential and re-type both. A password rotated on one side leaves the client failing its digest challenge while the dashboard looks healthy.
  3. Verify the server address. The SIP server hostname and port must be exactly the values the dashboard displays for the credential, not a value from an old provisioning email or a previous provider.
  4. Match the transport. UDP, TCP, and TLS are not interchangeable: a client set to TLS against a UDP port (or the reverse) fails its handshake and never registers. Use the transport the dashboard lists.
  5. Check NAT and firewall. The device’s network must allow outbound SIP to the displayed port, and the router’s SIP ALG must be off; ALG rewriting of REGISTER packets is the classic cause of a client that authenticates (never a 401) but never completes registration.
  6. Read the delta. If the client claims Registered but details.last_register_at is still stale, its REGISTER goes somewhere else: a second account profile, a mistyped hostname, or a blocked keepalive. Capture the client’s registration log at this step; you will want it for escalation.
A 401 in the client log points at step 2; a timeout points at steps 3 to 5.

​
Common misdiagnoses

  • Do not rotate the API key. Request authentication already succeeded; the 412 is returned after auth, on the device-registration check. Rotating the key changes nothing about the refusal.
  • Do not delete and re-create the SIP credential. Registration state lives on the device, not on the credential row. Re-creating the credential invalidates the username and password every phone already holds, turning one unregistered device into several.
  • Do not wait for the call to queue or retry later. The 412 is a pre-flight refusal: nothing is placed, queued, or retried server-side. The call goes through only after the device shows Registered and you dial again.
  • Do not change the caller ID or the destination. Those checks run after the registration gate and are not what refused the request.

​
When it keeps failing

If the softphone shows Registered and the refusal still fires, open a support ticket with three things so the attempt can be traced without a back-and-forth:
  1. meta.request_id from the refused response.
  2. details.sip_credential_id from the same response.
  3. A registration-log excerpt from the softphone covering the refusal window: the REGISTER attempts and the responses (or timeouts) they received.
  • Voice channel — the voice surface overview, including where SIP credentials live under Settings → Voice.
  • Browser softphone guide — running the credential in the in-browser softphone instead of a desk phone.
  • SIP credential provisioning — issuing, capping, and rotating credentials.
  • Troubleshooting: SIP trunk — a different surface. A SIP trunk connects your carrier or PBX to Orbit, while a SIP credential registers a single device; if your refusal is SIP_TRUNK_UNREGISTERED (503) rather than this code, that is the runbook you want.
  • Error codes reference — the full envelope catalogue.