Resources
Troubleshooting
An index of every symptom and the page that treats it. Start here when something is broken and you are not sure where to look.
Troubleshooting lives next to the thing that broke: rejected requests in Get started, missing deliveries in Webhooks, a call that went wrong in Calls. That is the right place for it once you know which layer failed, and no help at all when you do not. So this page is the way in. Find the line that matches what you actually saw, and follow it.
Find your symptom#
| What you saw | Where it is treated |
|---|---|
Every request comes back 401 UNAUTHORIZED | Authentication failures: the ApiKey scheme, and the invisible damage a copied key picks up |
403 FORBIDDEN, on a key that works elsewhere | Authentication failures: the key is valid, the tenant is not its own |
400 VALIDATION_ERROR on requests made with an organization key | Authentication failures: an organization key needs X-Tenant-Id on every tenant-scoped request |
404 on a resource you are looking at in the dashboard | Authentication failures: you are almost certainly authenticated as the wrong tenant |
| An error code you do not recognize | Errors: the envelope, every status, and why to branch on error.code |
| You dialled the number and nothing answered | Calls and assistant behavior: number assignment, failover mode, and whether a call record exists at all |
| The assistant says the wrong thing, or ignores a change you just made | Calls and assistant behavior: unsubstituted placeholders, competing prompt surfaces, and configuration read at call start |
| A tool is never called, however clearly you ask for it | Calls and assistant behavior: attachment, description, parameters, and your response time |
| The assistant called your tool and then stumbled | Tool calls to your server: the exact request shape and the response it expects |
| A caller asked for a person and heard dead air | Transfers: a cold hand-off to an unstaffed line has already left OnCore |
| The whisper talks over the destination's greeting | Transfers: warmWhisperDelaySeconds |
| A webhook never showed up | Webhooks not arriving: which URL the event was configured to reach, and whether you failed before responding |
| A delivery arrives and your handler rejects it | Webhooks not arriving: the shared secret, and the three ways signature checks break |
| The same event is processed twice | Webhooks not arriving: dedupe on the delivery id |
| Nothing reaches the handler running on your own machine | Receive webhooks on localhost: the local-only causes, ruled out first |
429, or requests failing in bursts under load | Rate limits: detecting a throttle, backing off with jitter, and sending fewer requests |
| A duplicate resource after you retried a create | API conventions: POST is not idempotent; reconcile before retrying |
Symptoms specific to one channel#
Each channel documents its own rejections next to the endpoints that produce them.
| What you saw | Where it is treated |
|---|---|
| A browser call fails to connect | Browser voice calls: status by status, including the deliberately opaque 404 |
| A web chat session or message is rejected | Web chat: session, message, and messaging-backend failures |
Enabling the SMS channel returns 400 | SMS: enabling needs a linked Twilio number |
WhatsApp onboarding ends in failed | WhatsApp: every terminal failureReason and what it means |
When you cannot name the symptom#
"It hung up on me" and "the transfer didn't work" fit four different layers, and picking the wrong one costs a day of editing prompts that were never involved. Debugging a voice agent is the method for locating the failure first: four layers, the evidence each one leaves, and the order to look in. Work through it before you change any configuration.
Still stuck#
Two checks pay for themselves before you escalate.
Reduce to the smallest request that still fails. If a bare curl with nothing but the Authorization header succeeds, the problem is in your client rather than your key. Authentication failures has the minimal reproduction.
Check the running API. The interactive API explorer is generated from the live service, so it settles any disagreement between these pages and what you are actually calling.
Some behavior is deliberately outside the public contract. The relevant page states that boundary explicitly instead of guessing or pointing at an undocumented route. Start with Capabilities and availability when the real question is whether a workflow has a supported developer surface.
When you do hand it over, send whoever supports your OnCore account the five things in Escalating with something useful: the call id and time, the exact transcript turn where behavior diverged, what you expected instead, whether it reproduces, and (for an API failure) the error.code with metadata.timestamp and metadata.path. A call id turns a conversation into an investigation.
Next steps#
- FAQ: the questions that come up before anything breaks.
- Debugging a voice agent: how to locate a failure in one layer before fixing it.
- Production readiness: the checks that stop most of this reaching live traffic.
- Glossary: what each noun in the API owns, when a page assumes you know.