Getting started
Troubleshooting your first run
Your first session did not fill the form? Nearly every first-run failure is one of the five below, so start from the symptom you see. The fix is usually one click in your workspace or one line in your configuration.
| What you see | What it is | Fix |
|---|---|---|
| NETWORK — “Could not reach Speechineer” | The request never got an answer — connectivity, or the browser blocked the request (check its console). | If the browser console shows a blocked cross-origin request, your origin was refused — check baseUrl for typos and tell us the origin you serve from. Otherwise check connectivity and retry. |
| FORM_VERSION_NOT_PUBLISHED (in the error message) | The version your code names exists but is a draft. | Publish it from the form's header (Publish this version), or point version at the published one. |
| Fields never fill — no error anywhere | The form's field ids and the ids your code writes into disagree. A mismatched id is not an error; the value just lands under a key you never read. | Log the recognized values and compare their keys with your inputs. The form's ids are the truth; rename on whichever side is wrong. |
| MICROPHONE_DENIED | Microphone access was blocked, or the page is not on a secure origin (HTTPS or localhost). Worth asking again. | Serve over HTTPS or localhost and surface the browser's permission prompt again — offer a retry button. |
| AUTH_MODE_MISMATCH / AUTH_SIGNATURE_REQUIRED (in the error message) | The token's alg does not match the API key's auth mode (Signed keys accept only PS256; Unsigned keys only alg=none). The workspace or key requires a PS256-signed token; alg=none was presented. | Check which client the page resolves and which mode its key carries — one app can hold both (see Authentication). |
Tip
When the failure is your app's own doing — the microphone and network failures above are — offer a retry button instead of ending the session.
Whether a session failed to start or while running, the code is in error.code and the error's class tells the families apart. The complete list, and how to handle errors in each framework: Errors.