Documentation

Troubleshooting

Every symptom below is listed as your switch or your portal shows it, with the cause and the one check that confirms it. Start with the code your switch logged on the INVITE, or with the call record in Calls — between them they identify almost every failure without anyone reading a log.

Three places the answer is#

Nearly every problem is identified by one of these before anybody opens a log file.

1. The response your switch logged on the INVITE. The code and its reason phrase name the check that failed.
2. The call record. Calls in the portal, or GET /calls. The fields that matter are status, sip_code, end_reason, billsec, transcript_status, analysis_status and processing_error.
3. The evidence on the call. Each call record carries the SIP message flow, the recording, the transcript and the media capture, and can be exported as one offline bundle.

API=https://your-ovs-host.example   # your API base URL
OVS_KEY=ovs_...                     # an API key from Developers in the portal

curl -s "$API/api/calls?limit=5" -H "X-API-Key: $OVS_KEY"
# {"total":1,"items":[{"id":"...","status":"completed","sip_code":200,"end_reason":"bye",
#   "billsec":42,"transcript_status":"done","analysis_status":"done","processing_error":null, ...}]}

Calls rejected with 403#

Three different checks answer 403, and they mean opposite things: one is your configuration, one is your own automation working as intended, and one is your account. The reason phrase tells them apart, and so does whether a call record appears.

403 IP not whitelisted#

Whitelisting is by the public source address of the packet — the address after NAT. On most deployments that is the SBC's egress address, not the PBX's own address, and the two are frequently different.

curl -s $API/api/customer/ips -H "X-API-Key: $OVS_KEY"
# [{"id":"...","cidr":"203.0.113.10/32","label":"sbc-1","destination_id":null,
#   "enabled":true,"created_at":"..."}]

• Is the entry enabled? A disabled entry is skipped entirely. enabled must be true.
• Is the address the one that leaves your network? Confirm it from an outbound test on the switch itself, not from its interface configuration.
• Did the switch fail over? A second SBC, a new node or a changed provider address sends from an address nobody added.
• Did an addition fail? 422 CIDR too broad: minimum prefix length is /16 means the range is wider than policy allows (/16 for IPv4, /48 for IPv6); 409 CIDR overlaps a range registered to another account means the range is already claimed — narrow it to the exact address you send from.

403 Blocked by rule#

This is your own automation. A rule of the form "probability at or above N and the recommendation is block → block this caller for H hours" puts the caller's number under a control, and every later call from that number is refused at the ingress until the control expires or you release it.

curl -s $API/api/automation/controls -H "X-API-Key: $OVS_KEY"
# {"total":1,"limit":50,"offset":0,"items":[{"id":"...","ani":"+15550100","action":"block",
#   "reason":"...","expires_at":"...","released_at":null,"created_at":"..."}]}

curl -s -X POST $API/api/automation/controls/<control_id>/release -H "X-API-Key: $OVS_KEY"

By default the list shows only controls that are in force right now; add include_released=true to see released and expired history. A blocked attempt is deliberately written to the call record so the block is auditable — that record is how you prove to a caller that they were rejected, and when.

Other codes your switch sees#

No audio, or audio in one direction only#

The media relays through us, so both endpoints must be able to reach our media address, and we must be able to reach both of them. One-way audio is almost always one firewall rule.

The call connected but there is no verdict#

A verdict normally appears within about a minute of hang-up. When it does not, analysis_status and processing_error on the call record say why. Analysis runs only for answered calls that finished and lasted at least the minimum analysis length.

GET /calls/{id}/analysis answers 404 Analysis not available (status: …) and GET /calls/{id}/transcript answers 404 Transcript not available (status: …) whenever the status is not done — the status in the message is the same one the table above explains.

A call sits in ringing and never clears#

ringing means we relayed your INVITE and are still waiting for a final response from your destination. It resolves one of three ways:

The destination answers late

Normal. The onward INVITE is given two minutes before it times out with 408.

Nothing ever comes back

The row is closed automatically five minutes after it started, with status: stale and billsec 0. Nothing is charged. Repeated stale rows mean your destination is not reachable from the ingress address, or is silently dropping the INVITE.

The record is holding a port

Unanswered rows count towards your concurrent limit until they are closed, so a run of unreachable calls can produce 486 Busy Here on good ones. Fix the destination and the backlog clears itself.

An answered call that ends as stale is different: the call really happened, the end-of-call notification did not arrive, and the record was finalized afterwards — billed up to the limit that was applied to it and still analyzed.

A recording, transcript or capture is missing#

Retention windows are set by the operator of your deployment, separately for recordings, media captures and SIP logs. If you need a call kept, export it — the bundle is self-contained and opens with no account and no network. See Security for how deletion works.

Alert e-mails are not arriving#

Work down this list. The test button under Alerts settles most of it in one click.

curl -s -X POST $API/api/customer/alert-rules/<rule_id>/test -H "X-API-Key: $OVS_KEY"
# {"sent":true,"error":null,"latency_ms":412,"recipients":["ops@acme.example"]}
# 409 when e-mail delivery is not configured on the deployment

• A 409 on the test means outbound e-mail is not configured on your deployment at all. That is an operator setting — raise it with them.
• Is the rule enabled, and does the call actually match it? A rule fires only when the probability is at or above its threshold and the category and recommendation are in its lists. An empty list means "any".
• Recipients. A rule with no recipients sends to the account e-mail address, not to nobody.
• Throttling. A rule with a throttle window suppresses a repeat to the same recipients inside that window. Set it to zero while testing.
• Only analyzed calls alert. A call that was skipped or failed analysis has no verdict to alert on — start there instead.
• The obvious one. Check the spam folder and any inbound filter for the sending address before blaming the platform.

Every new account starts with one enabled rule that e-mails the account address on calls scoring 90 or above with a block recommendation. If you never edited it, that is the only rule you have.

Webhooks are not delivered#

Send one test delivery. It uses the same envelope, signature and headers as a real event and reports exactly what happened.

curl -s -X POST $API/api/customer/webhook/test -H "X-API-Key: $OVS_KEY"
# {"delivered":true,"status_code":200,"error":null,"latency_ms":183}
# {"delivered":false,"status_code":null,"error":"webhook_not_configured","latency_ms":0}

If deliveries arrive but your receiver rejects them, check the signature on the raw body, before any JSON parsing or re-serialization: X-OVS-Signature is sha256= followed by the hex HMAC-SHA256 of the body under your webhook secret. X-OVS-Event names the event and X-OVS-Delivery is a delivery id you can use to make your handler idempotent — a retry repeats it.

An API request is rejected as unauthorized#

Quick answers#

Why is my call rejected with 403 IP not whitelisted?

The public source address of the INVITE is not inside any enabled entry on your IP list. It is the address after NAT, which is often your SBC's egress address rather than the PBX's own, and an OPTIONS ping succeeding does not prove it: OPTIONS is answered for any address, only an INVITE is checked against the list.

How do I tell an IP rejection from an automation block? Both answer 403.

Look in Calls. A caller blocked by one of your automation rules leaves a call record with status failed and end reason blocked_by_rule; a call refused because the source IP is not whitelisted leaves no record at all. The reason phrase on the SIP response also differs: Blocked by rule versus IP not whitelisted.

Why does a call have a recording but no analysis?

Check analysis_status and processing_error on the call. Common causes are a call shorter than the minimum analysis length (skipped), a codec other than G.711 (unsupported_codec), and audio that only ever flowed in one direction (no_rtp_streams).

Why are my webhooks not arriving?

Send a test delivery from the portal or POST /customer/webhook/test: it reports delivered, the upstream status code and the error. A non-https URL, or a hostname that resolves to a private or loopback address, is refused permanently and is never retried.

What to send when you escalate#

Include enough to identify the call without a conversation:

• The call id from the portal, or the SIP Call-ID if the call never produced a record.
• The time and time zone, and the source address the INVITE came from.
• The exact response your switch logged, reason phrase included.
• What you already checked from this page.