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). Recoverable. | 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). Recoverable — ask again. | Serve over HTTPS or localhost and surface the browser's permission prompt again. error.recoverable is true — 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
error.recoverable is true — 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 error.phase tells the two apart. The complete list, and how to handle errors in each framework: Errors.